JavaScript / Node.js

interface Snapshot {
  id: string;
  brain_id: string;

  // Core 16 fields
  name: string;
  type: "Belief" | "Model" | "Rule" | "Conviction" | "Principle";
  core: string;
  one_liner: string | null;
  story: string | null;
  moment: string | null;
  emotion: Record<string, unknown> | null;
  source: string | null;
  trigger_pattern: string | null;
  method: string | null;
  steps: string | null;
  filter: string | null;
  challenge: string | null;
  break_test: string | null;
  risks: string | null;
  proof: string | null;

  // Metadata
  confidence: number;
  significance_score: number;
  tags: string[];
  source_type: string;
  source_id: string | null;
  created_at: string;
  updated_at: string;
}

interface SearchResult extends Snapshot {
  similarity: string;
}

interface CrystallizeResponse {
  data: { snapshots: Snapshot[]; count: number };
  usage: {
    totalTokensIn: number;
    totalTokensOut: number;
    model: string;
    phases: Record<string, { tokensIn: number; tokensOut: number }>;
    embeddingTokens: number;
    totalTokens: number;
  };
  meta: {
    rawInsightCount: number;
    refinedCount: number;
    finalCount: number;
    durationMs: number;
  };
}

interface ListResponse {
  data: Snapshot[];
  count: number;
}

interface ProfileResponse {
  data: {
    id: string;
    email: string;
    plan: string;
    snapshot_count: number;
    search_count: number;
    limits: {
      snapshots: number;
      searches: number;
      api_rate: number;
    };
  };
}

const BASE_URL = "https://neuralsnap.ai/api/v1";

class NeuralSnapClient {
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
    const res = await fetch(`${BASE_URL}${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
        ...init.headers,
      },
    });
    if (!res.ok) {
      const err = await res.json().catch(() => ({}));
      throw new Error(`NeuralSnap ${res.status}: ${err.error || res.statusText}`);
    }
    return res.json();
  }

  /** Create a new snapshot */
  async createSnapshot(data: {
    name: string;
    core: string;
    type?: string;
    confidence?: number;
    tags?: string[];
    [key: string]: unknown;
  }): Promise<{ data: Snapshot }> {
    return this.request("/snapshots", {
      method: "POST",
      body: JSON.stringify(data),
    });
  }

  /** List snapshots with pagination */
  async listSnapshots(params?: {
    limit?: number;
    offset?: number;
    type?: string;
  }): Promise<ListResponse> {
    const qs = new URLSearchParams();
    if (params?.limit) qs.set("limit", String(params.limit));
    if (params?.offset) qs.set("offset", String(params.offset));
    if (params?.type) qs.set("type", params.type);
    const q = qs.toString();
    return this.request(`/snapshots${q ? `?${q}` : ""}`);
  }

  /** Get a single snapshot by ID */
  async getSnapshot(id: string): Promise<{ data: Snapshot }> {
    return this.request(`/snapshots/${id}`);
  }

  /** Update an existing snapshot */
  async updateSnapshot(
    id: string,
    data: Partial<Omit<Snapshot, "id" | "brain_id" | "created_at" | "updated_at">>
  ): Promise<{ data: Snapshot }> {
    return this.request(`/snapshots/${id}`, {
      method: "PUT",
      body: JSON.stringify(data),
    });
  }

  /** Delete a snapshot by ID */
  async deleteSnapshot(id: string): Promise<{ data: { success: boolean } }> {
    return this.request(`/snapshots/${id}`, { method: "DELETE" });
  }

  /** Semantic search across your brain */
  async search(
    query: string,
    limit = 10
  ): Promise<{ data: SearchResult[]; count: number; query: string; mode: string }> {
    return this.request(
      `/snapshots/search?q=${encodeURIComponent(query)}&limit=${limit}`
    );
  }

  /** Crystallize raw text into Neural Snapshots */
  async crystallize(
    text: string,
    sourceType = "api"
  ): Promise<CrystallizeResponse> {
    return this.request("/crystallize", {
      method: "POST",
      body: JSON.stringify({ text, source_type: sourceType }),
    });
  }

  /** Get your profile and usage stats */
  async getProfile(): Promise<ProfileResponse> {
    return this.request("/profile");
  }
}

export default NeuralSnapClient;

import NeuralSnapClient from "./neuralsnap";

const client = new NeuralSnapClient(process.env.NEURALSNAP_API_KEY!);

async function main() {
  // 1. Create a snapshot manually
  const { data: snap } = await client.createSnapshot({
    name: "Short-form video outperforms blogs",
    core: "TikTok and Reels drive 3x more signups than blog posts at lower cost",
    type: "Conviction",
    confidence: 0.85,
    tags: ["marketing", "content", "growth"],
  });
  console.log("Created:", snap.id);

  // 2. List all snapshots
  const { data: snapshots, count } = await client.listSnapshots({ limit: 10, offset: 0 });
  console.log(`Found ${count} snapshots`);
  for (const s of snapshots) {
    console.log(`  • ${s.name} (${s.type})`);
  }

  // 3. Get a single snapshot
  const { data: single } = await client.getSnapshot(snap.id);
  console.log(`Fetched: ${single.name}`);

  // 4. Update a snapshot
  const { data: updated } = await client.updateSnapshot(snap.id, {
    confidence: 0.95,
    tags: ["marketing", "content", "growth", "verified"],
  });
  console.log(`Updated confidence: ${updated.confidence}`);

  // 5. Semantic search
  const { data: results } = await client.search("content marketing strategy");
  for (const r of results) {
    console.log(`  [${r.similarity}] ${r.name}`);
  }

  // 6. Get profile
  const { data: profile } = await client.getProfile();
  console.log(`Plan: ${profile.plan}, Snapshots: ${profile.snapshot_count}`);

  // 7. Crystallize a meeting transcript
  const crystal = await client.crystallize(
    `Team standup — Jan 20 2026

Sarah: Auth migration is done. Clerk is live in staging.
Mike: Scoped the walkthrough component. Custom build is 2 weeks
but worth it for the polish.
Dana: Simplified onboarding wireframes approved. Starting
implementation today.
Sarah: Target Feb 1 for staging deploy — 3 weeks of testing
before launch.`,
    "conversation"
  );

  console.log(`Crystallized ${crystal.data.count} snapshots (${crystal.usage.totalTokens} tokens)`);
  for (const s of crystal.data.snapshots) {
    console.log(`  • ${s.name} [confidence: ${s.confidence}]`);
  }

  // 8. Delete a snapshot
  await client.deleteSnapshot(snap.id);
  console.log("Deleted snapshot");
}

main().catch(console.error);