@dreamingai/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,2450 @@
+// ============================================================
+// Dreaming AI — TypeScript SDK
+//
+// The primary client SDK for Dreaming AI Platform.
+// Used by: TekkoStudio Web, Tekko AI Mobile (Expo), Node.js apps
+//
+// Zero dependencies — uses native fetch API.
+// ============================================================
+
+// ─── Types (mirror @dreaming/core types for SDK consumers) ───
+
+export interface Memory {
+  id: string;
+  userId: string;
+  appId: string;
+  content: string;
+  memoryType: string;
+  memoryTier: number;
+  importance: number;
+  confidence: number;
+  accessCount: number;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  lastAccessed?: string;
+}
+
+export interface MemorySearchResult {
+  memory: Memory;
+  relevance: number;
+  decayScore?: number;
+  effectiveScore?: number;
+}
+
+export interface Entity {
+  id: string;
+  name: string;
+  entityType: string;
+  properties: Record<string, unknown>;
+}
+
+export interface Triple {
+  id: string;
+  subject: string;
+  predicate: string;
+  object: string;
+  validFrom?: string;
+  validTo?: string;
+  confidence: number;
+}
+
+export interface OceanProfile {
+  userId: string;
+  openness: number;
+  conscientiousness: number;
+  extraversion: number;
+  agreeableness: number;
+  neuroticism: number;
+  mbtiType?: string;
+  confidence: number;
+  sampleCount: number;
+}
+
+export interface LinguisticFingerprint {
+  userId: string;
+  formality: number;
+  vocabRichness: number;
+  avgSentenceLength: number;
+  emojiUsage: number;
+  dominantTone: string;
+}
+
+export interface SleeptimeInsight {
+  id: number;
+  type: string;
+  content: string;
+  createdAt: string;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  total: number;
+  offset: number;
+  limit: number;
+  hasMore: boolean;
+}
+
+export interface MeterStatus {
+  subscriptionTier: string;
+  modelTier: 'efficient' | 'smart' | 'genius';
+  modelTierName: string;
+  modelTierIcon: string;
+  modelTierDescription: string;
+  primaryModel: string;
+  fallbackModel: string;
+  maxTokens: number;
+  availableTiers: Array<{
+    key: string;
+    name: string;
+    icon: string;
+    description: string;
+    primaryModel: string;
+  }>;
+  tierMapping: Record<string, string>;
+  usage: {
+    callsThisMonth: number;
+    tokensThisMonth: number;
+    avgLatencyMs: number;
+    fallbackRate: string;
+  };
+}
+
+export interface MeterUsage {
+  daily: Array<{
+    day: string;
+    model_tier: string;
+    model_used: string;
+    calls: number;
+    total_tokens_in: number;
+    total_tokens_out: number;
+    avg_latency: number;
+    fallback_count: number;
+  }>;
+  byFeature: Array<{
+    feature: string;
+    model_tier: string;
+    calls: number;
+    total_tokens: number;
+  }>;
+}
+
+// ─── SDK Configuration ───────────────────────────────────────
+
+export interface DreamingClientConfig {
+  apiKey: string;
+  appId: string;
+  baseUrl?: string;
+  timeout?: number;
+}
+
+// ─── HTTP Client ─────────────────────────────────────────────
+
+class HttpClient {
+  private baseUrl: string;
+  private headers: Record<string, string>;
+  private timeout: number;
+
+  constructor(config: DreamingClientConfig) {
+    this.baseUrl = (config.baseUrl ?? 'https://api.dreaming.ai').replace(/\/$/, '');
+    this.headers = {
+      'Authorization': `Bearer ${config.apiKey}`,
+      'X-Dreaming-App-Id': config.appId,
+      'Content-Type': 'application/json',
+    };
+    this.timeout = config.timeout ?? 30_000;
+  }
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const error = await res.json().catch(() => ({ message: res.statusText })) as { code?: string; message?: string };
+        throw new DreamingError(error.code ?? 'API_ERROR', error.message ?? res.statusText, res.status);
+      }
+
+      return await res.json() as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  get<T>(path: string): Promise<T> { return this.request('GET', path); }
+  post<T>(path: string, body?: unknown): Promise<T> { return this.request('POST', path, body); }
+  patch<T>(path: string, body?: unknown): Promise<T> { return this.request('PATCH', path, body); }
+  delete<T>(path: string): Promise<T> { return this.request('DELETE', path); }
+}
+
+// ─── Error Class ─────────────────────────────────────────────
+
+export class DreamingError extends Error {
+  code: string;
+  status: number;
+
+  constructor(code: string, message: string, status: number) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = 'DreamingError';
+  }
+}
+
+// ─── Resource Clients ────────────────────────────────────────
+
+class MemoriesClient {
+  constructor(private http: HttpClient) {}
+
+  async create(input: {
+    userId: string;
+    content: string;
+    type?: string;
+    importance?: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<Memory> {
+    return this.http.post('/v1/memories', input);
+  }
+
+  async list(userId: string, options?: {
+    limit?: number;
+    offset?: number;
+    types?: string[];
+  }): Promise<PaginatedResponse<Memory>> {
+    const params = new URLSearchParams({ userId });
+    if (options?.limit) params.set('limit', String(options.limit));
+    if (options?.offset) params.set('offset', String(options.offset));
+    if (options?.types) params.set('types', options.types.join(','));
+    return this.http.get(`/v1/memories?${params}`);
+  }
+
+  async get(id: string): Promise<Memory> {
+    return this.http.get(`/v1/memories/${id}`);
+  }
+
+  async delete(id: string): Promise<{ success: boolean }> {
+    return this.http.delete(`/v1/memories/${id}`);
+  }
+
+  async search(input: {
+    userId: string;
+    query: string;
+    limit?: number;
+    types?: string[];
+    crossApp?: boolean;
+    includeDecayScore?: boolean;
+  }): Promise<MemorySearchResult[]> {
+    return this.http.post('/v1/memories/search', input);
+  }
+
+  async recall(input: {
+    userId: string;
+    query: string;
+    limit?: number;
+    includeDecayScore?: boolean;
+  }): Promise<MemorySearchResult[]> {
+    return this.http.post('/v1/memories/recall', input);
+  }
+}
+
+class DreamingApiClient {
+  constructor(private http: HttpClient) {}
+
+  async process(input: {
+    userId: string;
+    conversation: Array<{ role: string; content: string }>;
+  }): Promise<{ queued: number }> {
+    return this.http.post('/v1/dreaming/process', input);
+  }
+
+  async consolidate(userId: string): Promise<{
+    promoted: number;
+    merged: number;
+    evicted: number;
+  }> {
+    return this.http.post('/v1/dreaming/consolidate', { userId });
+  }
+
+  async getInsights(userId: string, limit?: number): Promise<SleeptimeInsight[]> {
+    const params = new URLSearchParams({ userId });
+    if (limit) params.set('limit', String(limit));
+    return this.http.get(`/v1/dreaming/insights?${params}`);
+  }
+
+  async getStatus(): Promise<Record<string, number>> {
+    return this.http.get('/v1/dreaming/status');
+  }
+}
+
+class GraphClient {
+  constructor(private http: HttpClient) {}
+
+  async addEntity(userId: string, name: string, entityType?: string, properties?: Record<string, unknown>): Promise<Entity> {
+    return this.http.post('/v1/graph/entities', { userId, name, entityType, properties });
+  }
+
+  async addTriple(userId: string, subject: string, predicate: string, object: string, options?: {
+    validFrom?: string;
+    validTo?: string;
+    confidence?: number;
+  }): Promise<Triple> {
+    return this.http.post('/v1/graph/triples', { userId, subject, predicate, object, ...options });
+  }
+
+  async query(userId: string, options?: {
+    subject?: string;
+    predicate?: string;
+    object?: string;
+    validAt?: string;
+    limit?: number;
+  }): Promise<Triple[]> {
+    return this.http.post('/v1/graph/query', { userId, ...options });
+  }
+
+  async getEntityFacts(userId: string, entityName: string): Promise<Triple[]> {
+    return this.http.get(`/v1/graph/entities/${encodeURIComponent(entityName)}/facts?userId=${userId}`);
+  }
+}
+
+class PersonalityClient {
+  constructor(private http: HttpClient) {}
+
+  async getOcean(userId: string): Promise<OceanProfile> {
+    return this.http.get(`/v1/personality/ocean?userId=${userId}`);
+  }
+
+  async analyzeOcean(userId: string, text: string): Promise<OceanProfile> {
+    return this.http.post('/v1/personality/analyze', { userId, text });
+  }
+
+  async getFingerprint(userId: string): Promise<LinguisticFingerprint> {
+    return this.http.get(`/v1/personality/fingerprint?userId=${userId}`);
+  }
+}
+
+// ─── Status Types ────────────────────────────────────────────
+
+export type AiState = 'idle' | 'thinking' | 'chatting' | 'creating' | 'learning' | 'dreaming' | 'evolving';
+
+export interface AiStatus {
+  state: AiState;
+  detail: string;
+  since: number;
+  bgProcesses: string[];
+}
+
+export interface BrainHealth {
+  state: string;
+  memories: number;
+  memoriesWithEmbeddings: number;
+  memoryBlocks: number;
+  kgEntities: number;
+  hasOcean: boolean;
+  hasFingerprint: boolean;
+  healthy: boolean;
+  uptime: number;
+}
+
+export interface QuotaUsage {
+  tier: string;
+  memory_entries: number;
+  max_memories: number;
+  shade_count: number;
+  max_shades: number;
+  used_bytes: number;
+  max_bytes: number;
+  storage_used_mb: number;
+  storage_limit_mb: number;
+}
+
+// ─── Sync/Privacy Types ──────────────────────────────────────
+
+export type ConsentStatus = 'synced' | 'paused' | 'pending' | 'declined';
+
+export interface SyncSettings {
+  userId: string;
+  enabled: boolean;
+  categories: Record<string, boolean>;
+  updatedAt: string;
+}
+
+export interface SyncConsent {
+  id: string;
+  domain: string;
+  name: string;
+  memberCount: number;
+  consentStatus: ConsentStatus;
+  lastSync: string;
+}
+
+// ─── Status Client ───────────────────────────────────────────
+
+class StatusClient {
+  constructor(private http: HttpClient) {}
+
+  /** Get current AI cognitive state (for orb rendering) */
+  async getStatus(userId?: string): Promise<AiStatus> {
+    const params = userId ? `?userId=${userId}` : '';
+    return this.http.get(`/v1/status${params}`);
+  }
+
+  /** Get detailed brain health metrics (for settings page) */
+  async getBrainHealth(userId?: string): Promise<BrainHealth> {
+    const params = userId ? `?userId=${userId}` : '';
+    return this.http.get(`/v1/status/brain${params}`);
+  }
+
+  /** Get quota usage and limits */
+  async getQuota(userId?: string): Promise<QuotaUsage> {
+    const params = userId ? `?userId=${userId}` : '';
+    const res = await this.http.get<{ data: QuotaUsage }>(`/v1/admin/quota${params}`);
+    return (res as any).data || res;
+  }
+}
+
+// ─── Sync Client ─────────────────────────────────────────────
+
+class SyncClient {
+  constructor(private http: HttpClient) {}
+
+  /** Get user's global sync settings */
+  async getSettings(userId?: string): Promise<SyncSettings> {
+    const params = userId ? `?userId=${userId}` : '';
+    const res = await this.http.get<{ data: SyncSettings }>(`/v1/sync/settings${params}`);
+    return (res as any).data || res;
+  }
+
+  /** Update sync settings (global toggle + category toggles) */
+  async updateSettings(input: {
+    userId?: string;
+    enabled?: boolean;
+    categories?: Record<string, boolean>;
+  }): Promise<SyncSettings> {
+    const res = await this.http.post<{ data: SyncSettings }>('/v1/sync/settings', input);
+    return (res as any).data || res;
+  }
+
+  /** Get consent status for all partner workspaces */
+  async getConsents(userId?: string, appId?: string): Promise<SyncConsent[]> {
+    const params = new URLSearchParams();
+    if (userId) params.set('userId', userId);
+    if (appId) params.set('appId', appId);
+    const res = await this.http.get<{ data: { workspaces: SyncConsent[] } }>(`/v1/sync/consent?${params}`);
+    return (res as any).data?.workspaces || [];
+  }
+
+  /** Accept, pause, resume, or decline sync with a target workspace */
+  async updateConsent(input: {
+    userId?: string;
+    targetWorkspaceId: string;
+    action: 'accept' | 'pause' | 'resume' | 'decline';
+    domain?: string;
+    name?: string;
+  }): Promise<SyncConsent> {
+    const res = await this.http.post<{ data: SyncConsent }>('/v1/sync/consent', {
+      target_workspace_id: input.targetWorkspaceId,
+      action: input.action,
+      userId: input.userId,
+      domain: input.domain,
+      name: input.name,
+    });
+    return (res as any).data || res;
+  }
+
+  /** Get privacy exposure toggles */
+  async getExposure(userId?: string, appId?: string): Promise<Record<string, boolean>> {
+    const params = new URLSearchParams();
+    if (userId) params.set('userId', userId);
+    if (appId) params.set('appId', appId);
+    const res = await this.http.get<{ data: Record<string, boolean> }>(`/v1/privacy/exposure?${params}`);
+    return (res as any).data || res;
+  }
+
+  /** Update privacy exposure toggles */
+  async updateExposure(toggles: Record<string, boolean>, userId?: string): Promise<Record<string, boolean>> {
+    const res = await this.http.post<{ data: any }>('/v1/privacy/exposure', {
+      toggles, userId,
+    });
+    return (res as any).data?.toggles || (res as any).data || toggles;
+  }
+}
+
+// ─── Context Client ──────────────────────────────────────────
+
+class ContextClient {
+  constructor(private http: HttpClient) {}
+
+  /** Get pre-built context string for injection into LLM prompts */
+  async getContext(userId: string): Promise<{ context: string; memories: number; personality: string }> {
+    return this.http.get(`/v1/memories/recall?userId=${userId}&limit=10`);
+  }
+
+  /** Before-chat hook: enrich messages with context (for non-middleware integrations) */
+  async beforeChat(input: {
+    userId: string;
+    messages: Array<{ role: string; content: string }>;
+  }): Promise<Array<{ role: string; content: string }>> {
+    const res = await this.http.post<{ messages: Array<{ role: string; content: string }> }>('/v1/dreaming/process', {
+      userId: input.userId,
+      conversation: input.messages,
+    });
+    return (res as any).messages || input.messages;
+  }
+
+  /** After-chat hook: queue conversation for sleeptime processing */
+  async afterChat(input: {
+    userId: string;
+    messages: Array<{ role: string; content: string }>;
+  }): Promise<{ queued: number }> {
+    return this.http.post('/v1/dreaming/process', {
+      userId: input.userId,
+      conversation: input.messages,
+    });
+  }
+}
+
+// ─── Meter Client ────────────────────────────────────────────
+// Smart Model Metering — lets partners/vendors show AI quality tier
+// in their apps, display upgrade prompts, and track usage.
+//
+// Usage:
+//   const badge = await client.meter.getBadge('user-123');
+//   // → { icon: '🟢', label: 'Efficient AI', color: '#22c55e' }
+//
+//   if (badge.canUpgrade) {
+//     showUpgradePrompt(badge.upgradeMessage);
+//   }
+
+/** Pre-built UI badge for displaying AI tier in partner apps */
+export interface MeterBadge {
+  /** Tier key: 'efficient' | 'smart' | 'genius' */
+  tier: string;
+  /** Display icon emoji */
+  icon: string;
+  /** Human-readable label (e.g., "Smart AI") */
+  label: string;
+  /** CSS-ready hex color for the badge */
+  color: string;
+  /** Short description of the tier */
+  description: string;
+  /** Primary model name (for transparency) */
+  model: string;
+  /** Whether the user can upgrade to a higher tier */
+  canUpgrade: boolean;
+  /** The next tier name if upgradeable */
+  nextTier?: string;
+  /** A ready-to-use upgrade CTA message */
+  upgradeMessage?: string;
+}
+
+const TIER_COLORS: Record<string, string> = {
+  efficient: '#22c55e',  // green-500
+  smart: '#3b82f6',      // blue-500
+  genius: '#a855f7',     // purple-500
+};
+
+const TIER_ORDER = ['efficient', 'smart', 'genius'];
+
+class MeterClient {
+  constructor(private http: HttpClient) {}
+
+  /** Get current model tier status for the authenticated user */
+  async getStatus(userId?: string): Promise<MeterStatus> {
+    const params = userId ? `?userId=${userId}` : '';
+    const res = await this.http.get<{ data: MeterStatus }>(`/v1/meter/status${params}`);
+    return (res as any).data || res;
+  }
+
+  /** Get detailed usage history */
+  async getUsage(userId: string, options?: { days?: number; limit?: number }): Promise<MeterUsage> {
+    const params = new URLSearchParams({ userId });
+    if (options?.days) params.set('days', String(options.days));
+    if (options?.limit) params.set('limit', String(options.limit));
+    const res = await this.http.get<{ data: MeterUsage }>(`/v1/meter/usage?${params}`);
+    return (res as any).data || res;
+  }
+
+  /**
+   * Get a ready-to-use UI badge for displaying the AI tier.
+   * Partners can drop this directly into their app UI.
+   *
+   * @example
+   * ```tsx
+   * const badge = await dreaming.meter.getBadge('user-123');
+   * return (
+   *   <div style={{ background: badge.color, borderRadius: 12, padding: '4px 12px' }}>
+   *     {badge.icon} {badge.label}
+   *   </div>
+   * );
+   * ```
+   */
+  async getBadge(userId?: string): Promise<MeterBadge> {
+    const status = await this.getStatus(userId);
+    const tier = status.modelTier;
+    const tierIndex = TIER_ORDER.indexOf(tier);
+    const canUpgrade = tierIndex < TIER_ORDER.length - 1;
+    const nextTier = canUpgrade ? TIER_ORDER[tierIndex + 1] : undefined;
+    const nextTierName = nextTier
+      ? status.availableTiers.find(t => t.key === nextTier)?.name
+      : undefined;
+
+    return {
+      tier,
+      icon: status.modelTierIcon,
+      label: `${status.modelTierName} AI`,
+      color: TIER_COLORS[tier] || '#6b7280',
+      description: status.modelTierDescription,
+      model: status.primaryModel,
+      canUpgrade,
+      nextTier: nextTierName,
+      upgradeMessage: canUpgrade
+        ? `Upgrade to ${nextTierName} AI for smarter, deeper insights powered by ${status.availableTiers.find(t => t.key === nextTier)?.primaryModel || 'a premium model'}.`
+        : undefined,
+    };
+  }
+
+  /** Quick check: is this user on the highest AI tier? */
+  async isGeniusTier(userId?: string): Promise<boolean> {
+    const status = await this.getStatus(userId);
+    return status.modelTier === 'genius';
+  }
+
+  /** Quick check: can this user upgrade to a better AI tier? */
+  async canUpgrade(userId?: string): Promise<boolean> {
+    const status = await this.getStatus(userId);
+    const tierIndex = TIER_ORDER.indexOf(status.modelTier);
+    return tierIndex < TIER_ORDER.length - 1;
+  }
+
+  /**
+   * Get a formatted usage summary string for dashboards.
+   *
+   * @example
+   * ```
+   * "🔵 Smart AI — 45 calls, 12.5k tokens this month (avg 230ms)"
+   * ```
+   */
+  async getUsageSummary(userId?: string): Promise<string> {
+    const status = await this.getStatus(userId);
+    const u = status.usage;
+    const tokens = u.tokensThisMonth >= 1000
+      ? `${(u.tokensThisMonth / 1000).toFixed(1)}k`
+      : String(u.tokensThisMonth);
+    return `${status.modelTierIcon} ${status.modelTierName} AI — ${u.callsThisMonth} calls, ${tokens} tokens this month (avg ${u.avgLatencyMs}ms)`;
+  }
+}
+
+// ─── Main Client ─────────────────────────────────────────────
+
+export class DreamingClient {
+  readonly memories: MemoriesClient;
+  readonly dreaming: DreamingApiClient;
+  readonly graph: GraphClient;
+  readonly personality: PersonalityClient;
+  readonly status: StatusClient;
+  readonly sync: SyncClient;
+  readonly context: ContextClient;
+  readonly meter: MeterClient;
+  readonly activities: ActivityClient;
+  readonly constraints: ConstraintClient;
+  readonly chat: ChatClient;
+  readonly knowledge: KnowledgeClient;
+  readonly web: WebClient;
+  readonly identity: IdentityClient;
+  readonly friends: FriendsClient;
+  readonly proactive: ProactiveClient;
+  readonly notifications: NotificationsClient;
+  readonly evolution: EvolutionClient;
+  readonly dna: DnaClient;
+  readonly partnerTokens: PartnerTokensClient;
+
+  constructor(config: DreamingClientConfig) {
+    const http = new HttpClient(config);
+    this.memories = new MemoriesClient(http);
+    this.dreaming = new DreamingApiClient(http);
+    this.graph = new GraphClient(http);
+    this.personality = new PersonalityClient(http);
+    this.status = new StatusClient(http);
+    this.sync = new SyncClient(http);
+    this.context = new ContextClient(http);
+    this.meter = new MeterClient(http);
+    this.activities = new ActivityClient(http, config);
+    this.constraints = new ConstraintClient(http);
+    this.chat = new ChatClient(http);
+    this.knowledge = new KnowledgeClient(http);
+    this.web = new WebClient(http);
+    this.identity = new IdentityClient(http);
+    this.friends = new FriendsClient(http);
+    this.proactive = new ProactiveClient(http);
+    this.notifications = new NotificationsClient(http);
+    this.evolution = new EvolutionClient(http);
+    this.dna = new DnaClient(http);
+    this.partnerTokens = new PartnerTokensClient(http);
+  }
+
+  /**
+   * Flush any buffered activity events before shutdown.
+   * Call this in your app's cleanup/beforeunload handler.
+   */
+  async flush(): Promise<void> {
+    await this.activities.flush();
+  }
+}
+
+// ─── Knowledge Client ────────────────────────────────────────
+// RAG knowledge base for partners. Upload docs, search, toggle
+// modules. Supports multi-format: text, markdown, CSV, JSON,
+// HTML, URL, base64, PDF.
+//
+// Usage:
+//   await dreaming.knowledge.upload({
+//     appId: 'active365',
+//     title: 'Training Plan',
+//     content: markdownText,
+//     moduleId: 'fitness-guides',
+//   });
+//
+//   const chunks = await dreaming.knowledge.search('running tips', { appId: 'active365' });
+//
+//   await dreaming.knowledge.toggleModule('fitness-guides', { appId: 'active365', enabled: false });
+//
+
+export interface KnowledgeDoc {
+  docId: string;
+  title: string;
+  chunkCount: number;
+  fileSizeBytes: number;
+  format: string;
+  domain: string;
+  status: string;
+}
+
+export interface KnowledgeChunk {
+  id: number;
+  doc_id: string;
+  content: string;
+  chunk_index: number;
+  domain: string;
+  topic: string;
+  importance: number;
+  doc_title?: string;
+  relevance?: number;
+}
+
+export interface KnowledgeModule {
+  module_id: string;
+  enabled: boolean;
+  priority: number;
+  doc_count: number;
+  chunk_count: number;
+}
+
+class KnowledgeClient {
+  constructor(private http: HttpClient) {}
+
+  /**
+   * Upload a document to the knowledge base.
+   * Supports: text, markdown, CSV, JSON, HTML, URL, base64, PDF.
+   * Auto-detects format from filename/content if sourceType is 'auto' or omitted.
+   *
+   * @example
+   * ```typescript
+   * // Upload markdown
+   * await dreaming.knowledge.upload({
+   *   appId: 'my-app',
+   *   title: 'Training Guide',
+   *   content: '# Running Tips\n\nStart slow...',
+   * });
+   *
+   * // Upload CSV data
+   * await dreaming.knowledge.upload({
+   *   appId: 'my-app',
+   *   title: 'Workout Log',
+   *   content: 'date,distance,time\n2024-01-01,5km,28min',
+   *   sourceType: 'csv',
+   * });
+   *
+   * // Upload with constraint auto-linking
+   * await dreaming.knowledge.upload({
+   *   appId: 'my-app',
+   *   userId: 'user-1',
+   *   title: 'Fitness Plan',
+   *   content: pdfBase64,
+   *   sourceType: 'base64',
+   *   feedConstraints: true,  // Auto-creates tags from content
+   * });
+   * ```
+   */
+  async upload(options: {
+    appId: string;
+    title: string;
+    content: string;
+    userId?: string;
+    moduleId?: string;
+    sourceType?: string;
+    sourceUrl?: string;
+    filename?: string;
+    scope?: 'app' | 'user';
+    feedConstraints?: boolean;
+    metadata?: Record<string, unknown>;
+  }): Promise<KnowledgeDoc> {
+    const res = await this.http.post<{ data: KnowledgeDoc }>('/v1/knowledge/upload', options);
+    return (res as any).data;
+  }
+
+  /**
+   * Upload content from a URL. Fetches and parses automatically.
+   *
+   * @example
+   * ```typescript
+   * await dreaming.knowledge.uploadUrl({
+   *   appId: 'my-app',
+   *   title: 'Running Tips Article',
+   *   url: 'https://example.com/running-tips',
+   * });
+   * ```
+   */
+  async uploadUrl(options: {
+    appId: string;
+    title: string;
+    url: string;
+    moduleId?: string;
+    userId?: string;
+  }): Promise<KnowledgeDoc> {
+    return this.upload({
+      appId: options.appId,
+      title: options.title,
+      content: options.url,
+      sourceType: 'url',
+      sourceUrl: options.url,
+      moduleId: options.moduleId,
+      userId: options.userId,
+    });
+  }
+
+  /** List uploaded documents. */
+  async listDocs(options?: {
+    appId?: string;
+    moduleId?: string;
+  }): Promise<KnowledgeDoc[]> {
+    const params = new URLSearchParams();
+    if (options?.appId) params.set('appId', options.appId);
+    if (options?.moduleId) params.set('moduleId', options.moduleId);
+    const res = await this.http.get<{ data: KnowledgeDoc[] }>(`/v1/knowledge/docs?${params}`);
+    return (res as any).data;
+  }
+
+  /** Get document details. */
+  async getDoc(docId: string): Promise<KnowledgeDoc> {
+    const res = await this.http.get<{ data: KnowledgeDoc }>(`/v1/knowledge/docs/${docId}`);
+    return (res as any).data;
+  }
+
+  /** View chunks of a document. */
+  async getChunks(docId: string): Promise<KnowledgeChunk[]> {
+    const res = await this.http.get<{ data: KnowledgeChunk[] }>(`/v1/knowledge/docs/${docId}/chunks`);
+    return (res as any).data;
+  }
+
+  /**
+   * Search knowledge base with semantic + keyword fallback.
+   *
+   * @example
+   * ```typescript
+   * const results = await dreaming.knowledge.search('running tips', {
+   *   appId: 'active365',
+   *   limit: 5,
+   *   domain: 'fitness',
+   * });
+   * ```
+   */
+  async search(query: string, options: {
+    appId: string;
+    domain?: string;
+    limit?: number;
+  }): Promise<KnowledgeChunk[]> {
+    const params = new URLSearchParams({ appId: options.appId, q: query });
+    if (options.domain) params.set('domain', options.domain);
+    if (options.limit) params.set('limit', String(options.limit));
+    const res = await this.http.get<{ data: KnowledgeChunk[] }>(`/v1/knowledge/search?${params}`);
+    return (res as any).data;
+  }
+
+  /** Delete a document and all its chunks. */
+  async deleteDoc(docId: string): Promise<void> {
+    await this.http.delete(`/v1/knowledge/docs/${docId}`);
+  }
+
+  /**
+   * Enable or disable a document (soft toggle).
+   * Disabled docs are excluded from search and chat context.
+   */
+  async toggleDoc(docId: string, enabled: boolean): Promise<void> {
+    await this.http.patch(`/v1/knowledge/docs/${docId}/toggle`, { enabled });
+  }
+
+  /**
+   * List knowledge modules with doc/chunk counts.
+   *
+   * @example
+   * ```typescript
+   * const modules = await dreaming.knowledge.listModules('active365');
+   * // [{ module_id: 'fitness-guides', enabled: true, doc_count: 3, chunk_count: 45 }]
+   * ```
+   */
+  async listModules(appId: string): Promise<KnowledgeModule[]> {
+    const res = await this.http.get<{ data: KnowledgeModule[] }>(`/v1/knowledge/modules?appId=${appId}`);
+    return (res as any).data;
+  }
+
+  /**
+   * Enable or disable an entire knowledge module.
+   * All docs in a disabled module are excluded from search.
+   */
+  async toggleModule(moduleId: string, options: { appId: string; enabled: boolean }): Promise<void> {
+    await this.http.patch(`/v1/knowledge/modules/${moduleId}/toggle`, options);
+  }
+
+  /**
+   * Re-chunk a document with different settings.
+   */
+  async reprocess(docId: string, options?: { chunkSize?: number; overlap?: number }): Promise<KnowledgeDoc> {
+    const res = await this.http.post<{ data: KnowledgeDoc }>(`/v1/knowledge/reprocess/${docId}`, options || {});
+    return (res as any).data;
+  }
+}
+
+// ─── Chat Client ─────────────────────────────────────────────
+// The genius middleware for partners who have their own LLM.
+//
+// PROBLEM: Partners already use GPT/Gemini/Claude in their app.
+// They don't want to replace their LLM — they want to ADD
+// memory + personality + goals to it.
+//
+// SOLUTION: Two-call pattern:
+//   1. BEFORE LLM call → dreaming.chat.enrich()  — get context
+//   2. AFTER  LLM call → dreaming.chat.learn()   — extract memories
+//
+// OR: One-line wrapper:
+//   const response = await dreaming.chat.wrapOpenAI(openai, userId, messages);
+//   // That's it. Memory-aware, personality-aware, goal-directed.
+//
+// ─── Usage Examples ──────────────────────────────────────────
+//
+// === Method 1: Manual (works with ANY LLM) ===
+//
+//   const ctx = await dreaming.chat.enrich(userId, userMessage);
+//   const response = await yourLlmCall([...ctx.messages, ...yourMessages]);
+//   await dreaming.chat.learn(userId, userMessage, response);
+//
+// === Method 2: OpenAI Wrapper (one line) ===
+//
+//   const reply = await dreaming.chat.wrapOpenAI(
+//     openai,        // your OpenAI client
+//     userId,
+//     messages,      // your conversation
+//     { model: 'gpt-4o' }
+//   );
+//
+// === Method 3: Gemini Wrapper ===
+//
+//   const reply = await dreaming.chat.wrapGemini(
+//     genAI,         // your Gemini client
+//     userId,
+//     userMessage,
+//     { model: 'gemini-2.0-flash' }
+//   );
+//
+
+/** Chat context returned from enrich() */
+export interface ChatContext {
+  messages: Array<{ role: string; content: string }>;
+  system?: string;
+  memories: any[];
+  metadata: {
+    memoriesUsed: number;
+    hasPersonality: boolean;
+    hasConstraints: boolean;
+    hasKnowledge: boolean;
+    appPersona: string | null;
+  };
+}
+
+/** Options for enrich() */
+export interface EnrichOptions {
+  maxMemories?: number;
+  includePersonality?: boolean;
+  includeConstraints?: boolean;
+  includeKnowledge?: boolean;
+  webGrounding?: boolean;
+  format?: 'openai' | 'anthropic' | 'raw';
+}
+
+/** Options for learn() */
+export interface LearnOptions {
+  metadata?: Record<string, unknown>;
+}
+
+class ChatClient {
+  constructor(private http: HttpClient) {}
+
+  // ─── Core: Enrich + Learn ─────────────────────────────────
+
+  /**
+   * BEFORE your LLM call: get memory/personality/goal context.
+   *
+   * Returns messages you inject into your conversation.
+   * Default format is OpenAI-compatible.
+   *
+   * @example
+   * ```typescript
+   * const ctx = await dreaming.chat.enrich('user-1', 'How should I train today?');
+   *
+   * // Inject into your OpenAI call:
+   * const response = await openai.chat.completions.create({
+   *   model: 'gpt-4o',
+   *   messages: [...ctx.messages, ...yourConversation],
+   * });
+   * ```
+   */
+  async enrich(userId: string, query: string, options?: EnrichOptions): Promise<ChatContext> {
+    const res = await this.http.post<{ data: ChatContext }>('/v1/chat/context', {
+      userId,
+      query,
+      maxMemories: options?.maxMemories,
+      includePersonality: options?.includePersonality,
+      includeConstraints: options?.includeConstraints,
+      includeKnowledge: options?.includeKnowledge,
+      webGrounding: options?.webGrounding,
+      format: options?.format || 'openai',
+    });
+    return (res as any).data;
+  }
+
+  /**
+   * AFTER your LLM responds: tell Dreaming to extract memories.
+   *
+   * This queues background tasks: memory extraction, entity detection,
+   * insight generation (goal-aware), and personality evolution.
+   *
+   * @example
+   * ```typescript
+   * await dreaming.chat.learn('user-1', userMessage, aiResponse);
+   * ```
+   */
+  async learn(userId: string, userMessage: string, aiResponse: string, options?: LearnOptions): Promise<{ learned: boolean; jobsQueued: string[] }> {
+    const res = await this.http.post<{ data: any }>('/v1/chat/learn', {
+      userId,
+      userMessage,
+      aiResponse,
+      metadata: options?.metadata,
+    });
+    return (res as any).data;
+  }
+
+  /**
+   * Full conversation version of learn.
+   */
+  async learnFromMessages(userId: string, messages: Array<{ role: string; content: string }>, options?: LearnOptions): Promise<{ learned: boolean; jobsQueued: string[] }> {
+    const res = await this.http.post<{ data: any }>('/v1/chat/learn', {
+      userId,
+      messages,
+      metadata: options?.metadata,
+    });
+    return (res as any).data;
+  }
+
+  // ─── One-Line Wrappers ────────────────────────────────────
+
+  /**
+   * Wrap an OpenAI client call. Memory + personality + goals, one line.
+   *
+   * @example
+   * ```typescript
+   * import OpenAI from 'openai';
+   * const openai = new OpenAI();
+   * const dreaming = new DreamingClient({ ... });
+   *
+   * // This one line gives your GPT memory, personality, and goals:
+   * const reply = await dreaming.chat.wrapOpenAI(openai, 'user-1', [
+   *   { role: 'user', content: 'How should I train today?' }
+   * ], { model: 'gpt-4o' });
+   *
+   * console.log(reply); // Goal-aware, memory-enriched response
+   * ```
+   */
+  async wrapOpenAI(
+    openai: any,
+    userId: string,
+    messages: Array<{ role: string; content: string }>,
+    options?: { model?: string; temperature?: number; maxTokens?: number },
+  ): Promise<string> {
+    // 1. Enrich with context
+    const lastUser = [...messages].reverse().find(m => m.role === 'user')?.content || '';
+    const ctx = await this.enrich(userId, lastUser, { format: 'openai' });
+
+    // 2. Call OpenAI with enriched messages
+    const enrichedMessages = [...ctx.messages, ...messages];
+    const completion = await openai.chat.completions.create({
+      model: options?.model || 'gpt-4o-mini',
+      messages: enrichedMessages,
+      temperature: options?.temperature,
+      max_tokens: options?.maxTokens,
+    });
+
+    const aiResponse = completion.choices?.[0]?.message?.content || '';
+
+    // 3. Learn from the conversation (non-blocking)
+    this.learn(userId, lastUser, aiResponse).catch(() => {});
+
+    return aiResponse;
+  }
+
+  /**
+   * Wrap a Google Gemini call. Memory + personality + goals, one line.
+   *
+   * @example
+   * ```typescript
+   * import { GoogleGenerativeAI } from '@google/generative-ai';
+   * const genAI = new GoogleGenerativeAI('YOUR_API_KEY');
+   * const dreaming = new DreamingClient({ ... });
+   *
+   * const reply = await dreaming.chat.wrapGemini(genAI, 'user-1',
+   *   'How should I train today?',
+   *   { model: 'gemini-2.0-flash' }
+   * );
+   * ```
+   */
+  async wrapGemini(
+    genAI: any,
+    userId: string,
+    userMessage: string,
+    options?: { model?: string; history?: Array<{ role: string; parts: Array<{ text: string }> }> },
+  ): Promise<string> {
+    // 1. Enrich
+    const ctx = await this.enrich(userId, userMessage, { format: 'raw' });
+
+    // 2. Call Gemini
+    const model = genAI.getGenerativeModel({ model: options?.model || 'gemini-2.0-flash' });
+    const chat = model.startChat({
+      history: options?.history || [],
+      systemInstruction: ctx.system || (ctx as any).systemPrompt || '',
+    });
+    const result = await chat.sendMessage(userMessage);
+    const aiResponse = result.response.text();
+
+    // 3. Learn (non-blocking)
+    this.learn(userId, userMessage, aiResponse).catch(() => {});
+
+    return aiResponse;
+  }
+
+  /**
+   * Wrap an Anthropic Claude call. Memory + personality + goals, one line.
+   *
+   * @example
+   * ```typescript
+   * import Anthropic from '@anthropic-ai/sdk';
+   * const anthropic = new Anthropic();
+   * const dreaming = new DreamingClient({ ... });
+   *
+   * const reply = await dreaming.chat.wrapAnthropic(anthropic, 'user-1', [
+   *   { role: 'user', content: 'How should I train today?' }
+   * ], { model: 'claude-sonnet-4-20250514' });
+   * ```
+   */
+  async wrapAnthropic(
+    anthropic: any,
+    userId: string,
+    messages: Array<{ role: string; content: string }>,
+    options?: { model?: string; maxTokens?: number },
+  ): Promise<string> {
+    // 1. Enrich (Anthropic format: system is separate)
+    const lastUser = [...messages].reverse().find(m => m.role === 'user')?.content || '';
+    const ctx = await this.enrich(userId, lastUser, { format: 'anthropic' });
+
+    // 2. Call Anthropic
+    const response = await anthropic.messages.create({
+      model: options?.model || 'claude-sonnet-4-20250514',
+      max_tokens: options?.maxTokens || 1024,
+      system: ctx.system || '',
+      messages,
+    });
+
+    const aiResponse = response.content?.[0]?.text || '';
+
+    // 3. Learn (non-blocking)
+    this.learn(userId, lastUser, aiResponse).catch(() => {});
+
+    return aiResponse;
+  }
+
+  /**
+   * Generic wrapper for any LLM. You provide the call function.
+   *
+   * @example
+   * ```typescript
+   * const reply = await dreaming.chat.wrap(
+   *   'user-1',
+   *   'How should I train today?',
+   *   async (systemPrompt, userMsg) => {
+   *     // Call your LLM however you want
+   *     return await myCustomLLM.generate(systemPrompt + '\n' + userMsg);
+   *   }
+   * );
+   * ```
+   */
+  async wrap(
+    userId: string,
+    userMessage: string,
+    llmCall: (systemPrompt: string, userMessage: string) => Promise<string>,
+    options?: EnrichOptions,
+  ): Promise<string> {
+    // 1. Enrich
+    const ctx = await this.enrich(userId, userMessage, { ...options, format: 'raw' });
+    const systemPrompt = (ctx as any).systemPrompt || ctx.system || '';
+
+    // 2. Call their LLM
+    const aiResponse = await llmCall(systemPrompt, userMessage);
+
+    // 3. Learn (non-blocking)
+    this.learn(userId, userMessage, aiResponse).catch(() => {});
+
+    return aiResponse;
+  }
+}
+
+// ─── Constraint Client ───────────────────────────────────────
+// Goals, tags, achievements with weighted influence on dreaming.
+//
+// Key concepts:
+//   Weight (0-100): how much this constraint influences AI behavior
+//   Pinned: won't fade or decay — user-locked focus area
+//   Tags: evolving labels that direct dreaming — AI-born or user-created
+//
+// Usage:
+//   // Set a goal
+//   await dreaming.constraints.setGoal('user-1', 'Run 5K in under 25 minutes', {
+//     category: 'fitness', weight: 90, targetValue: 25, unit: 'min',
+//     deadline: '2026-06-01', tags: ['running', 'cardio'],
+//   });
+//
+//   // Add a focus tag
+//   await dreaming.constraints.addTag('user-1', 'mindfulness', {
+//     category: 'wellness', weight: 70, pinned: true,
+//   });
+
+/** Constraint types */
+export type ConstraintType = 'goal' | 'sub_goal' | 'task' | 'checkpoint' | 'achievement';
+export type ConstraintStatus = 'active' | 'completed' | 'cancelled' | 'paused' | 'deleted';
+
+export interface Constraint {
+  id: string;
+  userId: string;
+  appId: string;
+  parentId?: string;
+  constraintType: ConstraintType;
+  title: string;
+  description: string;
+  status: ConstraintStatus;
+  weight: number;
+  priority: number;
+  category: string;
+  domain: string;
+  progress: number;
+  targetValue?: number;
+  currentValue: number;
+  unit: string;
+  deadline?: string;
+  completedAt?: string;
+  cancelledAt?: string;
+  pinned: boolean;
+  createdBy: string;
+  tags?: Array<{ tagKey: string; label: string; weight: number; status: string; pinned: boolean }>;
+  childCount?: number;
+  completedChildren?: number;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ConstraintTag {
+  id: string;
+  userId: string;
+  appId: string;
+  tagKey: string;
+  label: string;
+  category: string;
+  weight: number;
+  status: string;
+  pinned: boolean;
+  source: string;
+  birthReason: string;
+  matchCount: number;
+  constraintCount?: number;
+  createdAt: string;
+}
+
+export interface ConstraintContext {
+  constraints: Constraint[];
+  tags: ConstraintTag[];
+  contextString: string;
+  totalWeight: number;
+}
+
+class ConstraintClient {
+  constructor(private http: HttpClient) {}
+
+  // ─── Goals & Constraints ──────────────────────────────────
+
+  /**
+   * Create a goal, sub-goal, task, checkpoint, or achievement.
+   *
+   * @example
+   * ```typescript
+   * await dreaming.constraints.setGoal('user-1', 'Run 5K under 25min', {
+   *   category: 'fitness', weight: 90,
+   *   targetValue: 25, unit: 'min',
+   *   deadline: '2026-06-01',
+   *   tags: ['running', 'cardio'],
+   * });
+   * ```
+   */
+  async setGoal(userId: string, title: string, options?: {
+    type?: ConstraintType;
+    parentId?: string;
+    description?: string;
+    weight?: number;
+    priority?: number;
+    category?: string;
+    domain?: string;
+    targetValue?: number;
+    unit?: string;
+    deadline?: string;
+    pinned?: boolean;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+  }): Promise<Constraint> {
+    const res = await this.http.post<{ data: Constraint }>('/v1/constraints', {
+      userId,
+      title,
+      constraintType: options?.type || 'goal',
+      parentId: options?.parentId,
+      description: options?.description,
+      weight: options?.weight,
+      priority: options?.priority,
+      category: options?.category,
+      domain: options?.domain,
+      targetValue: options?.targetValue,
+      unit: options?.unit,
+      deadline: options?.deadline,
+      pinned: options?.pinned,
+      tags: options?.tags,
+      metadata: options?.metadata,
+    });
+    return (res as any).data;
+  }
+
+  /** Create a sub-goal under a parent goal */
+  async addSubGoal(userId: string, parentId: string, title: string, options?: Parameters<ConstraintClient['setGoal']>[2]): Promise<Constraint> {
+    return this.setGoal(userId, title, { ...options, type: 'sub_goal', parentId });
+  }
+
+  /** Create a task under a goal or sub-goal */
+  async addTask(userId: string, parentId: string, title: string, options?: Parameters<ConstraintClient['setGoal']>[2]): Promise<Constraint> {
+    return this.setGoal(userId, title, { ...options, type: 'task', parentId });
+  }
+
+  /** Create a checkpoint (milestone) */
+  async addCheckpoint(userId: string, parentId: string, title: string, options?: Parameters<ConstraintClient['setGoal']>[2]): Promise<Constraint> {
+    return this.setGoal(userId, title, { ...options, type: 'checkpoint', parentId });
+  }
+
+  /** Record an achievement */
+  async addAchievement(userId: string, title: string, options?: Parameters<ConstraintClient['setGoal']>[2]): Promise<Constraint> {
+    return this.setGoal(userId, title, { ...options, type: 'achievement' });
+  }
+
+  /**
+   * List constraints with optional filters.
+   */
+  async list(userId: string, options?: {
+    type?: ConstraintType;
+    status?: ConstraintStatus | 'all';
+    category?: string;
+    parentId?: string;
+    pinned?: boolean;
+  }): Promise<Constraint[]> {
+    const params = new URLSearchParams({ userId });
+    if (options?.type) params.set('type', options.type);
+    if (options?.status) params.set('status', options.status);
+    if (options?.category) params.set('category', options.category);
+    if (options?.parentId) params.set('parentId', options.parentId);
+    if (options?.pinned) params.set('pinned', 'true');
+    const res = await this.http.get<{ data: Constraint[] }>(`/v1/constraints?${params}`);
+    return (res as any).data;
+  }
+
+  /**
+   * Update a constraint's weight, status, progress, or other fields.
+   *
+   * @example
+   * ```typescript
+   * // Update progress
+   * await dreaming.constraints.update(goalId, { progress: 75 });
+   *
+   * // Change weight (influences how much AI focuses on this)
+   * await dreaming.constraints.update(goalId, { weight: 30 });
+   *
+   * // Complete a goal
+   * await dreaming.constraints.update(goalId, { status: 'completed' });
+   * ```
+   */
+  async update(constraintId: string, updates: {
+    title?: string;
+    description?: string;
+    status?: ConstraintStatus;
+    weight?: number;
+    priority?: number;
+    category?: string;
+    progress?: number;
+    currentValue?: number;
+    targetValue?: number;
+    deadline?: string;
+    pinned?: boolean;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Constraint> {
+    const res = await this.http.patch<{ data: Constraint }>(`/v1/constraints/${constraintId}`, updates);
+    return (res as any).data;
+  }
+
+  /** Complete a constraint */
+  async complete(constraintId: string): Promise<Constraint> {
+    return this.update(constraintId, { status: 'completed' });
+  }
+
+  /** Cancel a constraint */
+  async cancel(constraintId: string, reason?: string): Promise<Constraint> {
+    return this.update(constraintId, { status: 'cancelled', reason });
+  }
+
+  /** Pause a constraint (keeps weight but AI won't actively suggest) */
+  async pause(constraintId: string): Promise<Constraint> {
+    return this.update(constraintId, { status: 'paused' });
+  }
+
+  /** Resume a paused constraint */
+  async resume(constraintId: string): Promise<Constraint> {
+    return this.update(constraintId, { status: 'active' });
+  }
+
+  /** Pin a constraint (locks it from fading) */
+  async pin(constraintId: string): Promise<Constraint> {
+    return this.update(constraintId, { pinned: true });
+  }
+
+  /** Unpin a constraint */
+  async unpin(constraintId: string): Promise<Constraint> {
+    return this.update(constraintId, { pinned: false });
+  }
+
+  /** Set the weight (0-100) — how much the AI focuses on this */
+  async setWeight(constraintId: string, weight: number, reason?: string): Promise<Constraint> {
+    return this.update(constraintId, { weight: Math.min(Math.max(weight, 0), 100), reason });
+  }
+
+  /** Delete a constraint (soft delete) */
+  async delete(constraintId: string): Promise<void> {
+    await this.http.delete(`/v1/constraints/${constraintId}`);
+  }
+
+  /** Get change history for a constraint */
+  async getHistory(constraintId: string): Promise<Array<{ changeType: string; oldValue: string; newValue: string; reason: string; createdAt: string }>> {
+    const res = await this.http.get<{ data: any[] }>(`/v1/constraints/${constraintId}/history`);
+    return (res as any).data;
+  }
+
+  // ─── Tags ─────────────────────────────────────────────────
+
+  /**
+   * Create or update a focus tag.
+   *
+   * @example
+   * ```typescript
+   * await dreaming.constraints.addTag('user-1', 'mindfulness', {
+   *   category: 'wellness', weight: 70, pinned: true,
+   * });
+   * ```
+   */
+  async addTag(userId: string, tagKey: string, options?: {
+    label?: string;
+    category?: string;
+    weight?: number;
+    pinned?: boolean;
+    birthReason?: string;
+  }): Promise<ConstraintTag> {
+    const res = await this.http.post<{ data: ConstraintTag }>('/v1/constraints/tags', {
+      userId,
+      tagKey,
+      label: options?.label || tagKey,
+      category: options?.category,
+      weight: options?.weight,
+      pinned: options?.pinned,
+      source: 'user',
+      birthReason: options?.birthReason,
+    });
+    return (res as any).data;
+  }
+
+  /** List tags */
+  async listTags(userId: string, options?: {
+    status?: string;
+    category?: string;
+    pinned?: boolean;
+  }): Promise<ConstraintTag[]> {
+    const params = new URLSearchParams({ userId });
+    if (options?.status) params.set('status', options.status);
+    if (options?.category) params.set('category', options.category);
+    if (options?.pinned) params.set('pinned', 'true');
+    const res = await this.http.get<{ data: ConstraintTag[] }>(`/v1/constraints/tags?${params}`);
+    return (res as any).data;
+  }
+
+  /** Update a tag (weight, pin, category) */
+  async updateTag(tagId: string, updates: {
+    weight?: number;
+    pinned?: boolean;
+    status?: string;
+    category?: string;
+    label?: string;
+  }): Promise<ConstraintTag> {
+    const res = await this.http.patch<{ data: ConstraintTag }>(`/v1/constraints/tags/${tagId}`, updates);
+    return (res as any).data;
+  }
+
+  /** Pin a tag */
+  async pinTag(tagId: string): Promise<ConstraintTag> {
+    return this.updateTag(tagId, { pinned: true });
+  }
+
+  /** Set tag weight */
+  async setTagWeight(tagId: string, weight: number): Promise<ConstraintTag> {
+    return this.updateTag(tagId, { weight: Math.min(Math.max(weight, 0), 100) });
+  }
+
+  // ─── Context ──────────────────────────────────────────────
+
+  /**
+   * Get the weighted constraint context that the AI uses.
+   * Shows exactly how constraints + tags influence dreaming.
+   */
+  async getContext(userId: string): Promise<ConstraintContext> {
+    const res = await this.http.get<{ data: ConstraintContext }>(`/v1/constraints/context?userId=${userId}`);
+    return (res as any).data;
+  }
+}
+
+// ─── Activity Client ─────────────────────────────────────────
+// Lightweight activity tracking with client-side buffering.
+//
+// DESIGN GOALS:
+//   1. ZERO overhead on the app — track() is synchronous
+//   2. Events buffer locally and flush as a single batch
+//   3. Auto-flush every N seconds or when buffer is full
+//   4. Fire-and-forget — flush errors never crash the app
+//   5. Session management built-in
+//
+// Usage:
+//   dreaming.activities.track('user-123', 'screen_view', 'ProductDetail', {
+//     domain: 'shopping',
+//     data: { productId: 'abc', price: 29.99 },
+//   });
+//   // → Queues locally, flushes automatically every 5 seconds
+
+/** A single activity event to track */
+export interface ActivityEvent {
+  userId: string;
+  /** Category of activity: 'screen_view', 'button_click', 'feature_use', 'gesture', etc. */
+  activityType: string;
+  /** Specific name: 'ProductDetail', 'AddToCart', 'SearchQuery', etc. */
+  activityName: string;
+  /** Life domain: 'fitness', 'shopping', 'finance', 'social', etc. */
+  domain?: string;
+  /** Arbitrary data payload */
+  data?: Record<string, unknown>;
+  /** Duration in ms (for timed activities like screen dwell time) */
+  durationMs?: number;
+  /** Session ID (auto-generated if not provided) */
+  sessionId?: string;
+}
+
+/** Activity summary for a time period */
+export interface ActivitySummary {
+  activityType: string;
+  activityName: string;
+  count: number;
+  totalDurationMs: number;
+  lastAt: string;
+}
+
+/** Configuration for the activity buffer */
+export interface ActivityBufferConfig {
+  /** Max events to buffer before auto-flush (default: 20) */
+  bufferSize?: number;
+  /** Auto-flush interval in ms (default: 5000 = 5 seconds) */
+  flushIntervalMs?: number;
+  /** Disable auto-flush (for manual control) */
+  disableAutoFlush?: boolean;
+}
+
+class ActivityClient {
+  private buffer: ActivityEvent[] = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private sessionId: string;
+  private bufferSize: number;
+  private isFlushing = false;
+
+  constructor(
+    private http: HttpClient,
+    config: DreamingClientConfig & { activityBuffer?: ActivityBufferConfig },
+  ) {
+    const bufConfig = config.activityBuffer ?? {};
+    this.bufferSize = bufConfig.bufferSize ?? 20;
+    this.sessionId = `ses_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    if (!bufConfig.disableAutoFlush) {
+      const interval = bufConfig.flushIntervalMs ?? 5000;
+      this.flushTimer = setInterval(() => this.flush().catch(() => {}), interval);
+    }
+  }
+
+  /**
+   * Track a user activity event — SYNCHRONOUS, zero overhead.
+   * Events are queued locally and flushed as a batch automatically.
+   *
+   * @example
+   * ```typescript
+   * // Track a screen view
+   * dreaming.activities.track('user-123', 'screen_view', 'Dashboard');
+   *
+   * // Track a feature interaction with data
+   * dreaming.activities.track('user-123', 'feature_use', 'AIChat', {
+   *   domain: 'productivity',
+   *   data: { messageCount: 5, topic: 'project planning' },
+   *   durationMs: 45000,
+   * });
+   *
+   * // Track a button click
+   * dreaming.activities.track('user-123', 'button_click', 'UpgradeToProBtn', {
+   *   domain: 'billing',
+   * });
+   * ```
+   */
+  track(
+    userId: string,
+    activityType: string,
+    activityName: string,
+    options?: Omit<ActivityEvent, 'userId' | 'activityType' | 'activityName'>,
+  ): void {
+    this.buffer.push({
+      userId,
+      activityType,
+      activityName,
+      domain: options?.domain,
+      data: options?.data,
+      durationMs: options?.durationMs,
+      sessionId: options?.sessionId ?? this.sessionId,
+    });
+
+    // Auto-flush when buffer is full
+    if (this.buffer.length >= this.bufferSize) {
+      this.flush().catch(() => {});
+    }
+  }
+
+  /**
+   * Flush buffered events to the server.
+   * Called automatically by the timer/buffer-full, but you can call manually.
+   */
+  async flush(): Promise<number> {
+    if (this.buffer.length === 0 || this.isFlushing) return 0;
+    this.isFlushing = true;
+
+    // Take the current buffer and clear it
+    const events = [...this.buffer];
+    this.buffer = [];
+
+    try {
+      const res = await this.http.post<{ data: { inserted: number } }>('/v1/activities/batch', {
+        events,
+      });
+      return (res as any).data?.inserted ?? events.length;
+    } catch {
+      // Put events back on failure (will retry on next flush)
+      this.buffer.unshift(...events);
+      return 0;
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Query activity history for a user.
+   */
+  async getHistory(userId: string, options?: {
+    type?: string;
+    domain?: string;
+    days?: number;
+    limit?: number;
+  }): Promise<{ data: ActivityEvent[]; summary: ActivitySummary[]; total: number }> {
+    const params = new URLSearchParams({ userId });
+    if (options?.type) params.set('type', options.type);
+    if (options?.domain) params.set('domain', options.domain);
+    if (options?.days) params.set('days', String(options.days));
+    if (options?.limit) params.set('limit', String(options.limit));
+    return this.http.get(`/v1/activities?${params}`);
+  }
+
+  /** Get the current auto-generated session ID */
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  /** Start a new session (generates a new session ID) */
+  newSession(): string {
+    this.sessionId = `ses_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    return this.sessionId;
+  }
+
+  /** Get the number of buffered (unflushed) events */
+  get pendingCount(): number {
+    return this.buffer.length;
+  }
+
+  /** Stop the auto-flush timer (call before app shutdown after flush) */
+  destroy(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+}
+
+// ─── Web Grounding Client ────────────────────────────────────
+// Internet access for the AI brain. Controlled by DNA policy.
+//
+// Usage:
+//   const results = await dreaming.web.search('5K race events Jakarta', { appId: 'active365' });
+//   const policy = await dreaming.web.getPolicy('active365');
+//   await dreaming.web.updatePolicy('active365', { enabled: true, maxDailySearches: 100 });
+//
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  content: string;
+  description?: string;
+  publishedDate?: string;
+  source: string;
+}
+
+export interface WebCrawlResult {
+  url: string;
+  content: string;
+  title?: string;
+  description?: string;
+  source: string;
+  length: number;
+}
+
+export interface WebAccessPolicy {
+  enabled: boolean;
+  maxDailySearches: number;
+  allowedCategories: string[];
+  blockedDomains: string[];
+  requireRelevance: boolean;
+}
+
+export interface WebDailyUsage {
+  appId: string;
+  date: string;
+  searchCount: number;
+  crawlCount: number;
+  tokensUsed: number;
+}
+
+class WebClient {
+  constructor(private http: HttpClient) {}
+
+  /**
+   * Search the web. Respects DNA guardrails (must be enabled for the app).
+   * Results are cached for 24h.
+   *
+   * @example
+   * ```typescript
+   * const results = await dreaming.web.search('5K running tips', {
+   *   appId: 'active365',
+   *   limit: 5,
+   * });
+   * ```
+   */
+  async search(query: string, options: {
+    appId: string;
+    limit?: number;
+    format?: 'results' | 'prompt';
+    skipCache?: boolean;
+  }): Promise<WebSearchResult[]> {
+    const res = await this.http.post<{ data: { results: WebSearchResult[] } }>(
+      '/v1/web/search',
+      { query, ...options },
+    );
+    return (res as any).data.results;
+  }
+
+  /**
+   * Search and return formatted system prompt (for direct LLM injection).
+   */
+  async searchForPrompt(query: string, appId: string): Promise<string> {
+    const res = await this.http.post<{ data: { contextPrompt: string } }>(
+      '/v1/web/search',
+      { query, appId, format: 'prompt', limit: 3 },
+    );
+    return (res as any).data.contextPrompt || '';
+  }
+
+  /** Crawl a specific URL for content. */
+  async crawl(url: string, appId: string): Promise<WebCrawlResult | null> {
+    try {
+      const res = await this.http.post<{ data: WebCrawlResult }>('/v1/web/crawl', { url, appId });
+      return (res as any).data;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Get the web access policy for an app. */
+  async getPolicy(appId: string): Promise<WebAccessPolicy> {
+    const res = await this.http.get<{ data: WebAccessPolicy }>(`/v1/web/policy?appId=${appId}`);
+    return (res as any).data;
+  }
+
+  /**
+   * Update web access policy.
+   *
+   * @example
+   * ```typescript
+   * await dreaming.web.updatePolicy('active365', {
+   *   enabled: true,
+   *   maxDailySearches: 100,
+   *   blockedDomains: ['facebook.com'],
+   * });
+   * ```
+   */
+  async updatePolicy(appId: string, policy: Partial<WebAccessPolicy>): Promise<WebAccessPolicy> {
+    const res = await this.http.post<{ data: WebAccessPolicy }>('/v1/web/policy', { appId, ...policy });
+    return (res as any).data;
+  }
+
+  /** Get daily web usage stats for budget monitoring. */
+  async getUsage(appId: string, date?: string): Promise<WebDailyUsage> {
+    const params = date ? `appId=${appId}&date=${date}` : `appId=${appId}`;
+    const res = await this.http.get<{ data: WebDailyUsage }>(`/v1/web/usage?${params}`);
+    return (res as any).data;
+  }
+
+  /** Get user dreaming settings (all toggles). */
+  async getSettings(userId: string, appId?: string): Promise<Record<string, boolean>> {
+    const params = appId ? `userId=${userId}&appId=${appId}` : `userId=${userId}`;
+    const res = await this.http.get<{ data: Record<string, boolean> }>(`/v1/web/settings?${params}`);
+    return (res as any).data;
+  }
+
+  /** Update user dreaming settings (toggle features on/off). */
+  async updateSettings(userId: string, settings: Record<string, boolean>, appId?: string): Promise<Record<string, boolean>> {
+    const res = await this.http.post<{ data: Record<string, boolean> }>('/v1/web/settings', {
+      userId,
+      appId: appId || 'default',
+      ...settings,
+    });
+    return (res as any).data;
+  }
+}
+
+// ─── Identity Client ─────────────────────────────────────────
+// User names, AI names, social circle, cross-app sync.
+//
+// Usage:
+//   const identity = await dreaming.identity.get('user-1', 'active365');
+//   await dreaming.identity.setAiName('user-1', 'active365', 'Coach Buddy');
+//   const people = await dreaming.identity.getSocialCircle('user-1');
+//
+
+export interface UserIdentity {
+  userId: string;
+  appId: string;
+  userDisplayName: string;
+  userPreferredName: string;
+  userFullName: string;
+  aiName: string;
+  aiDefaultName: string;
+  source: string;
+  syncToHq: boolean;
+  syncFromHq: boolean;
+  effectiveAiName?: string;
+  effectiveUserName?: string;
+}
+
+export interface SocialPerson {
+  id: string;
+  userId: string;
+  appId: string;
+  personName: string;
+  relationship: string;
+  relationshipDetail: string;
+  nickname: string;
+  status: string;
+  mentionCount: number;
+  sentiment: number;
+  isCrossApp: boolean;
+  source: string;
+}
+
+class IdentityClient {
+  constructor(private http: HttpClient) {}
+
+  /** Get user identity (names, AI name, sync status). */
+  async get(userId: string, appId?: string): Promise<UserIdentity> {
+    const params = appId ? `userId=${userId}&appId=${appId}` : `userId=${userId}`;
+    const res = await this.http.get<{ data: UserIdentity }>(`/v1/identity?${params}`);
+    return (res as any).data;
+  }
+
+  /** Update user identity (display name, preferred name, etc). */
+  async update(userId: string, appId: string, updates: Partial<UserIdentity>): Promise<UserIdentity> {
+    const res = await this.http.post<{ data: UserIdentity }>('/v1/identity', { userId, appId, ...updates });
+    return (res as any).data;
+  }
+
+  /** Get the effective AI name for this user in this app. */
+  async getAiName(userId: string, appId?: string): Promise<string> {
+    const params = appId ? `userId=${userId}&appId=${appId}` : `userId=${userId}`;
+    const res = await this.http.get<{ data: { aiName: string } }>(`/v1/identity/ai-name?${params}`);
+    return (res as any).data.aiName;
+  }
+
+  /** Set a custom AI name (user-chosen or partner default). */
+  async setAiName(userId: string, appId: string, aiName: string, isPartnerDefault = false): Promise<string> {
+    const res = await this.http.post<{ data: { aiName: string } }>('/v1/identity/ai-name', {
+      userId, appId, aiName, isPartnerDefault,
+    });
+    return (res as any).data.aiName;
+  }
+
+  /** Get people the user knows (family, friends, colleagues). */
+  async getSocialCircle(userId: string, appId?: string, relationship?: string): Promise<SocialPerson[]> {
+    let params = `userId=${userId}`;
+    if (appId) params += `&appId=${appId}`;
+    if (relationship) params += `&relationship=${relationship}`;
+    const res = await this.http.get<{ data: SocialPerson[] }>(`/v1/identity/social?${params}`);
+    return (res as any).data;
+  }
+
+  /** Add a person to the user's social circle. */
+  async addPerson(userId: string, appId: string, person: {
+    name: string;
+    relationship: string;
+    relationshipDetail?: string;
+    nickname?: string;
+    sentiment?: number;
+  }): Promise<SocialPerson> {
+    const res = await this.http.post<{ data: SocialPerson }>('/v1/identity/social', {
+      userId, appId, ...person,
+    });
+    return (res as any).data;
+  }
+
+  /** Sync identity from HQ to a partner app. */
+  async syncFromHq(userId: string, appId: string): Promise<UserIdentity> {
+    const res = await this.http.post<{ data: UserIdentity }>('/v1/identity/sync', { userId, appId });
+    return (res as any).data;
+  }
+}
+
+// ─── Friends Client ──────────────────────────────────────────
+// AI-to-AI friendship system. Persistent connections between
+// user brains with shared memories and trust evolution.
+//
+// Usage:
+//   await dreaming.friends.request('user-1', 'user-2', { connectionType: 'friend' });
+//   const connections = await dreaming.friends.list('user-1');
+//
+
+export interface FriendConnection {
+  id: string;
+  user_a_id: string;
+  user_b_id: string;
+  status: string;
+  connection_type: string;
+  trust_level: number;
+  interaction_count: number;
+  friend_user_id?: string;
+  shared_count?: number;
+  exchange_count?: number;
+}
+
+export interface SharedMemory {
+  id: number;
+  connection_id: string;
+  source_user_id: string;
+  content: string;
+  domain: string;
+  memory_type: string;
+  importance: number;
+}
+
+class FriendsClient {
+  constructor(private http: HttpClient) {}
+
+  /** Send a friend request. */
+  async request(userId: string, friendUserId: string, options?: {
+    connectionType?: string;
+    sharedDomains?: string[];
+    message?: string;
+  }): Promise<FriendConnection> {
+    const res = await this.http.post<{ data: FriendConnection }>('/v1/friends/request', {
+      userId, friendUserId, ...options,
+    });
+    return (res as any).data;
+  }
+
+  /** Accept a friend connection. */
+  async accept(connectionId: string, options?: {
+    sharedDomains?: string[];
+    autoCommunicate?: boolean;
+  }): Promise<FriendConnection> {
+    const res = await this.http.post<{ data: FriendConnection }>(`/v1/friends/accept/${connectionId}`, options || {});
+    return (res as any).data;
+  }
+
+  /** Reject or block a connection. */
+  async reject(connectionId: string, block = false): Promise<void> {
+    await this.http.post(`/v1/friends/reject/${connectionId}`, { block });
+  }
+
+  /** List all connections for a user. */
+  async list(userId: string): Promise<FriendConnection[]> {
+    const res = await this.http.get<{ data: FriendConnection[] }>(`/v1/friends?userId=${userId}`);
+    return (res as any).data;
+  }
+
+  /** Get connection details. */
+  async get(connectionId: string): Promise<FriendConnection> {
+    const res = await this.http.get<{ data: FriendConnection }>(`/v1/friends/${connectionId}`);
+    return (res as any).data;
+  }
+
+  /** Trigger an AI-to-AI exchange. */
+  async exchange(connectionId: string, topic?: string, maxRounds?: number): Promise<{
+    connectionId: string;
+    exchangeRounds: number;
+    exchanges: any[];
+    trustLevel: number;
+  }> {
+    const res = await this.http.post<{ data: any }>(`/v1/friends/${connectionId}/exchange`, { topic, maxRounds });
+    return (res as any).data;
+  }
+
+  /** Get exchange conversation history. */
+  async conversations(connectionId: string, limit?: number): Promise<any[]> {
+    const params = limit ? `?limit=${limit}` : '';
+    const res = await this.http.get<{ data: any[] }>(`/v1/friends/${connectionId}/conversations${params}`);
+    return (res as any).data;
+  }
+
+  /** Get shared memories for a connection. */
+  async sharedMemories(connectionId: string, limit?: number): Promise<SharedMemory[]> {
+    const params = limit ? `?limit=${limit}` : '';
+    const res = await this.http.get<{ data: SharedMemory[] }>(`/v1/friends/${connectionId}/shared${params}`);
+    return (res as any).data;
+  }
+
+  /** Share a specific memory with a friend. */
+  async shareMemory(connectionId: string, userId: string, content: string, domain?: string, importance?: number): Promise<SharedMemory> {
+    const res = await this.http.post<{ data: SharedMemory }>(`/v1/friends/${connectionId}/share`, {
+      userId, content, domain, importance,
+    });
+    return (res as any).data;
+  }
+
+  /** Update connection settings. */
+  async update(connectionId: string, settings: {
+    userId?: string;
+    autoCommunicate?: boolean;
+    communicationFreq?: string;
+    connectionType?: string;
+    sharedDomains?: string[];
+  }): Promise<void> {
+    await this.http.request('PATCH', `/v1/friends/${connectionId}`, settings);
+  }
+}
+
+// ─── Proactive Client ────────────────────────────────────────
+// AI-initiated proactive suggestions. The brain decides when
+// to reach out to the user with helpful nudges.
+//
+
+export interface ProactiveSuggestion {
+  id: number;
+  userId: string;
+  appId: string;
+  type: string;
+  content: string;
+  priority: number;
+  trigger: string;
+  createdAt: string;
+}
+
+class ProactiveClient {
+  constructor(private http: HttpClient) {}
+
+  /** Trigger proactive evaluation for a user. */
+  async evaluate(userId: string, appId?: string): Promise<{ triggered: boolean; suggestion?: ProactiveSuggestion }> {
+    const res = await this.http.post<any>('/v1/proactive/evaluate', { userId, appId });
+    return res as any;
+  }
+
+  /** Get pending proactive suggestions. */
+  async getSuggestions(userId: string, appId?: string, limit?: number): Promise<ProactiveSuggestion[]> {
+    let params = `userId=${userId}`;
+    if (appId) params += `&appId=${appId}`;
+    if (limit) params += `&limit=${limit}`;
+    const res = await this.http.get<{ data: ProactiveSuggestion[] }>(`/v1/proactive/suggestions?${params}`);
+    return (res as any).data;
+  }
+
+  /** Dismiss a proactive suggestion. */
+  async dismiss(suggestionId: number | string): Promise<void> {
+    await this.http.post('/v1/proactive/dismiss', { suggestionId });
+  }
+}
+
+// ─── Notifications Client ────────────────────────────────────
+// Notification preferences, push tokens, and behavior timeline.
+//
+
+export interface NotificationPrefs {
+  channel: string;
+  pushToken: string;
+  pushPlatform: string;
+  quietStart: string;
+  quietEnd: string;
+  maxDaily: number;
+  enabled: boolean;
+}
+
+export interface BehaviorSignal {
+  id: number;
+  userId: string;
+  signalType: string;
+  value: number;
+  context: Record<string, unknown>;
+  createdAt: string;
+}
+
+class NotificationsClient {
+  constructor(private http: HttpClient) {}
+
+  /** Mark notifications as read. */
+  async markRead(ids: (number | string)[]): Promise<void> {
+    await this.http.post('/v1/proactive/read', { ids });
+  }
+
+  /** Act on a proactive suggestion. */
+  async act(suggestionId: number | string, action: string): Promise<any> {
+    const res = await this.http.post<any>('/v1/proactive/act', { suggestionId, action });
+    return res as any;
+  }
+
+  /** Get notification preferences. */
+  async getPrefs(userId: string, appId?: string): Promise<NotificationPrefs> {
+    let params = `userId=${userId}`;
+    if (appId) params += `&appId=${appId}`;
+    const res = await this.http.get<{ data: NotificationPrefs }>(`/v1/notifications/prefs?${params}`);
+    return (res as any).data;
+  }
+
+  /** Update notification preferences. */
+  async updatePrefs(userId: string, prefs: Partial<NotificationPrefs>, appId?: string): Promise<NotificationPrefs> {
+    const res = await this.http.request('PUT', '/v1/notifications/prefs', { userId, appId, ...prefs }) as any;
+    return res.data;
+  }
+
+  /** Register a push notification token. */
+  async registerPushToken(userId: string, token: string, platform: 'ios' | 'android' | 'web', appId?: string): Promise<void> {
+    await this.http.post('/v1/notifications/push-token', { userId, token, platform, appId });
+  }
+
+  /** Get behavior timeline (activity/mood history). */
+  async getTimeline(userId: string, options?: { days?: number; limit?: number }): Promise<any[]> {
+    let params = `userId=${userId}`;
+    if (options?.days) params += `&days=${options.days}`;
+    if (options?.limit) params += `&limit=${options.limit}`;
+    const res = await this.http.get<{ data: any[] }>(`/v1/behavior/timeline?${params}`);
+    return (res as any).data;
+  }
+
+  /** Get behavior signals. */
+  async getSignals(userId: string, type?: string): Promise<BehaviorSignal[]> {
+    let params = `userId=${userId}`;
+    if (type) params += `&type=${type}`;
+    const res = await this.http.get<{ data: BehaviorSignal[] }>(`/v1/behavior/signals?${params}`);
+    return (res as any).data;
+  }
+
+  /** Get behavior summary. */
+  async getSummary(userId: string): Promise<any> {
+    const res = await this.http.get<{ data: any }>(`/v1/behavior/summary?userId=${userId}`);
+    return (res as any).data;
+  }
+}
+
+// ─── Evolution Client ────────────────────────────────────────
+// Activity tracking, life domains, app features & events.
+// Transforms AI from conversation-centric to activity-aware.
+//
+
+export interface LifeDomain {
+  id: string;
+  userId: string;
+  name: string;
+  category: string;
+  importance: number;
+  progress: number;
+  status: string;
+}
+
+export interface AppFeature {
+  id: string;
+  appId: string;
+  featureName: string;
+  category: string;
+  description: string;
+}
+
+class EvolutionClient {
+  constructor(private http: HttpClient) {}
+
+  /** Track a single activity event. */
+  async trackActivity(activity: {
+    userId: string;
+    appId?: string;
+    activityType: string;
+    category?: string;
+    duration?: number;
+    intensity?: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<any> {
+    const res = await this.http.post<{ data: any }>('/v1/activities', activity);
+    return (res as any).data;
+  }
+
+  /** Track a batch of activities. */
+  async trackBatch(activities: Array<{
+    userId: string;
+    appId?: string;
+    activityType: string;
+    category?: string;
+    duration?: number;
+    metadata?: Record<string, unknown>;
+  }>): Promise<{ inserted: number }> {
+    const res = await this.http.post<any>('/v1/activities/batch', { activities });
+    return res as any;
+  }
+
+  /** Get activity history. */
+  async getActivities(userId: string, options?: { category?: string; limit?: number; days?: number }): Promise<any[]> {
+    let params = `userId=${userId}`;
+    if (options?.category) params += `&category=${options.category}`;
+    if (options?.limit) params += `&limit=${options.limit}`;
+    if (options?.days) params += `&days=${options.days}`;
+    const res = await this.http.get<{ data: any[] }>(`/v1/activities?${params}`);
+    return (res as any).data;
+  }
+
+  /** Get user's life domains. */
+  async getDomains(userId: string): Promise<LifeDomain[]> {
+    const res = await this.http.get<{ data: LifeDomain[] }>(`/v1/domains?userId=${userId}`);
+    return (res as any).data;
+  }
+
+  /** Create a life domain. */
+  async createDomain(domain: {
+    userId: string;
+    name: string;
+    category?: string;
+    importance?: number;
+  }): Promise<LifeDomain> {
+    const res = await this.http.post<{ data: LifeDomain }>('/v1/domains', domain);
+    return (res as any).data;
+  }
+
+  /** Update domain progress. */
+  async updateProgress(domainId: string, progress: number, note?: string): Promise<any> {
+    const res = await this.http.post<{ data: any }>(`/v1/domains/${domainId}/progress`, { progress, note });
+    return (res as any).data;
+  }
+
+  /** Get domain progress history. */
+  async getDomainHistory(domainId: string, limit?: number): Promise<any[]> {
+    const params = limit ? `?limit=${limit}` : '';
+    const res = await this.http.get<{ data: any[] }>(`/v1/domains/${domainId}/history${params}`);
+    return (res as any).data;
+  }
+
+  /** Register an app feature. */
+  async registerFeature(appId: string, feature: {
+    featureName: string;
+    category?: string;
+    description?: string;
+  }): Promise<AppFeature> {
+    const res = await this.http.post<{ data: AppFeature }>(`/v1/apps/${appId}/features`, feature);
+    return (res as any).data;
+  }
+
+  /** Emit an app event. */
+  async emitEvent(appId: string, event: {
+    eventType: string;
+    userId?: string;
+    payload?: Record<string, unknown>;
+  }): Promise<any> {
+    const res = await this.http.post<{ data: any }>(`/v1/apps/${appId}/events`, event);
+    return (res as any).data;
+  }
+
+  /** Get app context (features, recent events). */
+  async getAppContext(appId: string, userId?: string): Promise<any> {
+    const params = userId ? `?userId=${userId}` : '';
+    const res = await this.http.get<{ data: any }>(`/v1/apps/${appId}/context${params}`);
+    return (res as any).data;
+  }
+
+  /** Get or set user state (mood, role, context). */
+  async getUserState(userId: string): Promise<any> {
+    const res = await this.http.get<{ data: any }>(`/v1/user-state?userId=${userId}`);
+    return (res as any).data;
+  }
+
+  /** Update user state. */
+  async setUserState(userId: string, state: Record<string, unknown>): Promise<any> {
+    const res = await this.http.post<{ data: any }>('/v1/user-state', { userId, ...state });
+    return (res as any).data;
+  }
+}
+
+// ─── DNA Client ──────────────────────────────────────────────
+// App DNA management. Partners define their app's personality,
+// discipline, domains, guardrails, and knowledge seeds.
+//
+
+export interface AppDna {
+  appId: string;
+  appName: string;
+  discipline: string;
+  personaName: string;
+  boundaries: string;
+  defaultDomains: string[];
+  rootKnowledge: string[];
+  webAccess: Record<string, unknown>;
+}
+
+class DnaClient {
+  constructor(private http: HttpClient) {}
+
+  /** Get app DNA configuration. */
+  async get(appId: string): Promise<AppDna> {
+    const res = await this.http.get<{ data: AppDna }>(`/v1/apps/${appId}/dna`);
+    return (res as any).data;
+  }
+
+  /** Register or update app DNA. */
+  async update(appId: string, dna: Partial<AppDna>): Promise<AppDna> {
+    const res = await this.http.post<{ data: AppDna }>(`/v1/apps/${appId}/dna`, dna);
+    return (res as any).data;
+  }
+
+  /** Seed a new user's brain with app defaults. */
+  async seedUser(appId: string, userId: string): Promise<any> {
+    const res = await this.http.post<{ data: any }>(`/v1/apps/${appId}/seed`, { userId });
+    return (res as any).data;
+  }
+
+  /** List all registered apps. */
+  async listApps(): Promise<AppDna[]> {
+    const res = await this.http.get<{ data: AppDna[] }>('/v1/apps/directory');
+    return (res as any).data;
+  }
+}
+
+// ─── Partner Tokens Client ───────────────────────────────────
+// Token management for partner developers.
+//
+
+export interface PartnerToken {
+  id: string;
+  name: string;
+  key: string;
+  status: number;
+  quotaLimit: number;
+  usedQuota: number;
+  expiresAt?: string;
+}
+
+class PartnerTokensClient {
+  constructor(private http: HttpClient) {}
+
+  /** Create a child token. */
+  async create(options: {
+    name: string;
+    quotaLimit?: number;
+    models?: string[];
+    expiresIn?: string;
+    group?: string;
+  }): Promise<PartnerToken> {
+    const res = await this.http.post<{ data: PartnerToken }>('/v1/partner/tokens', options);
+    return (res as any).data;
+  }
+
+  /** List partner's tokens. */
+  async list(): Promise<PartnerToken[]> {
+    const res = await this.http.get<{ data: PartnerToken[] }>('/v1/partner/tokens');
+    return (res as any).data;
+  }
+
+  /** Revoke a token. */
+  async revoke(tokenId: string): Promise<void> {
+    await this.http.request('DELETE', `/v1/partner/tokens/${tokenId}`);
+  }
+
+  /** Update token settings. */
+  async update(tokenId: string, updates: Partial<{ quotaLimit: number; group: string; expiresAt: string }>): Promise<PartnerToken> {
+    const res = await this.http.request('PATCH', `/v1/partner/tokens/${tokenId}`, updates) as any;
+    return res.data;
+  }
+
+  /** Get token usage stats. */
+  async getUsage(tokenId: string): Promise<any> {
+    const res = await this.http.get<{ data: any }>(`/v1/partner/tokens/${tokenId}/usage`);
+    return (res as any).data;
+  }
+}
+
+// ─── Default Export ──────────────────────────────────────────
+
+export default DreamingClient;