mcpaas 0.1.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Wolfe James
+Copyright (c) 2026 WolfeJam
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,127 +1,115 @@
 # mcpaas
 
-**Your AI forgets you every session. MCPaaS remembers.**
+TypeScript SDK for [MCPaaS](https://mcpaas.live) — Context, on-demand.
 
-You re-explain your stack to Claude. Switch to Gemini — re-explain everything. Open Cursor — again. Every session. Every tool. Every time.
-
-That's the drift tax. [$49M/day](https://fafdev.tools/value) burned industry-wide.
-
-This SDK connects you to [MCPaaS](https://mcpaas.live) — persistent AI context that follows you across tools, sessions, and teams.
+Zero dependencies. Works with Bun, Node 18+, Deno, browsers, and edge runtimes.
 
 ## Install
 
 ```bash
 npm install mcpaas
+# or
+bun add mcpaas
 ```
 
 ## Quick Start
 
 ```typescript
-import { Radio } from 'mcpaas';
+import { MCPaaS } from 'mcpaas';
 
-const radio = new Radio('wss://mcpaas.live/beacon/radio');
-await radio.connect();
+const m = new MCPaaS();
 
-// Tune to your project's frequency
-await radio.tune('91.0');
+// Read a soul
+const soul = await m.getRawSoul('spacex');
+console.log(soul);
 
-// Your context arrives — from any AI, any session
-radio.onBroadcast((frequency, context) => {
-  console.log(`Context update on ${frequency} FM:`, context);
-});
-```
+// Score a namepoint
+const result = await m.score('faf');
+console.log(result.score, result.tierReady);
 
-That's it. Your context persists. Zero drift.
+// Check handle availability
+const check = await m.check('myhandle');
+console.log(check.available);
+```
 
-## How It Works
+## API
 
-MCPaaS uses the **Radio Protocol** — broadcast once, every AI receives.
+### Souls
 
-```
-Traditional (the tax):
-  You → Claude  (send 50KB context)
-  You → Grok    (send 50KB again)
-  You → Gemini  (send 50KB again)
-  = 3x cost, 3x latency, context drift
-
-Radio Protocol (the fix):
-  You → Broadcast to 91.0 FM (send once)
-  Claude  ← tuned to 91.0
-  Grok    ← tuned to 91.0
-  Gemini  ← tuned to 91.0
-  = 1x cost, instant, zero drift
+```typescript
+m.getSoul('faf')        // Structured soul content
+m.getRawSoul('spacex')  // Plain text soul
+m.listSouls()           // Stats: counts, top souls, operations
 ```
 
-## Multi-AI Example
+### Scoring
 
 ```typescript
-import { Radio } from 'mcpaas';
-
-const claude = new Radio('wss://mcpaas.live/beacon/radio');
-const grok   = new Radio('wss://mcpaas.live/beacon/radio');
-const gemini = new Radio('wss://mcpaas.live/beacon/radio');
+m.score('faf')                    // Score a namepoint
+m.scoreRepo('owner/repo')        // Score a GitHub repo
+m.leaderboard()                   // Top scored repos
+```
 
-await Promise.all([claude.connect(), grok.connect(), gemini.connect()]);
-await Promise.all([claude.tune('91.0'), grok.tune('91.0'), gemini.tune('91.0')]);
+### Directory & Discovery
 
-// All three AIs now share the same context, in real time
-claude.onBroadcast((f, ctx) => console.log('Claude:', ctx));
-grok.onBroadcast((f, ctx)   => console.log('Grok:', ctx));
-gemini.onBroadcast((f, ctx) => console.log('Gemini:', ctx));
+```typescript
+m.directory()           // Full namepoint directory
+m.check('handle')       // Handle availability + pricing
+m.count()               // Claimed/remaining counts
+m.discover()            // Discovery feed (namepoints + souls)
 ```
 
-## API
-
-### Constructor
+### Tag Intel
 
 ```typescript
-const radio = new Radio(url: string, options?: {
-  reconnect?: boolean;           // Auto-reconnect (default: true)
-  maxReconnectAttempts?: number; // Max attempts (default: 5)
-  reconnectDelay?: number;       // Delay in ms (default: 1000)
-  heartbeatInterval?: number;    // Ping interval (default: 30000)
-  debug?: boolean;               // Debug logging (default: false)
-});
+m.tagIntel()            // Tag patterns, co-occurrence, candidates, merges
+m.suggestTags('handle') // Suggest tags for a namepoint
 ```
 
-### Methods
+### Badges
 
-| Method | Description |
-|--------|-------------|
-| `connect()` | Connect to MCPaaS |
-| `tune(frequency)` | Subscribe to a frequency |
-| `untune(frequency)` | Unsubscribe from a frequency |
-| `disconnect()` | Disconnect |
-| `getState()` | `'DISCONNECTED'` \| `'CONNECTING'` \| `'CONNECTED'` \| `'RECONNECTING'` \| `'CLOSED'` |
-| `getTunedFrequencies()` | Set of tuned frequencies |
+```typescript
+m.badge('owner', 'repo')  // Returns SVG badge URL (sync)
+// => https://mcpaas.live/badge/owner/repo.svg
+```
 
-### Events
+### Globe
 
-| Event | Callback |
-|-------|----------|
-| `onBroadcast(fn)` | `(frequency, context) => void` |
-| `onConnect(fn)` | `() => void` |
-| `onDisconnect(fn)` | `(code?, reason?) => void` |
-| `onError(fn)` | `(error) => void` |
-| `onTuned(fn)` | `(frequency) => void` |
-| `onUntuned(fn)` | `(frequency) => void` |
+```typescript
+m.globe()  // Edge location stats from 300+ Cloudflare colos
+```
 
-## Why Bun?
+### Platform
 
-Anthropic acquired Bun in December 2025. Bun now powers Claude Code. This library is built for Bun first — native TypeScript, 7x faster WebSockets, zero config.
+```typescript
+m.health()  // Health check
+m.info()    // Server info
+```
 
-## Namepoints
+## Configuration
 
-Every frequency maps to a **namepoint** on MCPaaS — your permanent AI identity.
+```typescript
+const m = new MCPaaS({
+  baseUrl: 'https://mcpaas.live',  // default
+});
+```
 
-Free namepoints work. But `yourname.mcpaas.live` hits different than `user-38291.mcpaas.live`.
+## Error Handling
 
-**Claim yours before someone else does:** [mcpaas.live/claim](https://mcpaas.live/claim)
+```typescript
+import { MCPaaS, MCPaaSError } from 'mcpaas';
+
+try {
+  await m.getSoul('nonexistent');
+} catch (e) {
+  if (e instanceof MCPaaSError) {
+    console.log(e.status);  // HTTP status code
+    console.log(e.body);    // Response body
+    console.log(e.path);    // Request path
+  }
+}
+```
 
 ## License
 
 MIT
-
----
-
-Built by [Wolfe James](https://github.com/Wolfe-Jam) | Powered by [MCPaaS](https://mcpaas.live) | Format: [FAF](https://faf.one)

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * MCPaaS SDK — Context, on-demand.
+ * =================================
+ * Zero-dependency TypeScript client for the MCPaaS platform.
+ * Works with Bun, Node 18+, Deno, browsers, and edge runtimes.
+ *
+ * Usage:
+ *   import { MCPaaS } from 'mcpaas';
+ *   const m = new MCPaaS();
+ *   const soul = await m.getRawSoul('spacex');
+ */
+export interface MCPaaSOptions {
+    /** Base URL of the MCPaaS instance. Default: https://mcpaas.live */
+    baseUrl?: string;
+}
+export interface SoulStats {
+    date: string;
+    total_souls: number;
+    operations_today: Record<string, number>;
+    top_souls: Array<{
+        soul: string;
+        reads: number;
+    }>;
+}
+export interface ScoreResult {
+    handle: string;
+    score: number;
+    tierReady: boolean;
+    valid: boolean;
+    engine: string;
+}
+export interface RepoScore {
+    score: number;
+    repo: string;
+    hasFaf: boolean;
+    language: string;
+    stars: number;
+    description: string;
+}
+export interface LeaderboardResult {
+    top: Array<{
+        repo: string;
+        score: number;
+        language: string;
+    }>;
+    recent: Array<{
+        repo: string;
+        score: number;
+        language: string;
+    }>;
+    total: number;
+}
+export interface DirectoryEntry {
+    handle: string;
+    name: string;
+    tagline: string;
+    role: string;
+    avatar: number;
+    tags: string[];
+    userTags: string[];
+    score: number;
+}
+export interface DirectoryResult {
+    count: number;
+    namepoints: DirectoryEntry[];
+    userTagIndex: Array<{
+        tag: string;
+        count: number;
+    }>;
+}
+export interface CheckResult {
+    handle: string;
+    available: boolean;
+    price?: number;
+    tier?: string;
+}
+export interface CountResult {
+    claimed: number;
+    remaining: number;
+    tier: string;
+    price: string;
+    annual: string;
+    names: string[];
+}
+export interface DiscoverResult {
+    namepoints: DirectoryEntry[];
+    souls: string[];
+    totalSouls: number;
+}
+export interface TagProfile {
+    tag: string;
+    count: number;
+    cooccurs: Array<{
+        tag: string;
+        overlap: number;
+    }>;
+}
+export interface TagCandidate {
+    term: string;
+    count: number;
+    source: string;
+}
+export interface TagMerge {
+    canonical: string;
+    variants: string[];
+}
+export interface TagIntelResult {
+    tags: TagProfile[];
+    candidates: TagCandidate[];
+    merges: TagMerge[];
+    analysed: number;
+    updatedAt: string;
+}
+export interface SuggestResult {
+    handle: string;
+    existingTags: string[];
+    suggestions: string[];
+}
+export interface GlobeLocation {
+    code: string;
+    count: number;
+    lat: number;
+    lng: number;
+    city: string;
+    active: boolean;
+}
+export interface GlobeResult {
+    total: number;
+    activeLocations: number;
+    totalLocations: number;
+    locations: GlobeLocation[];
+    updated: string;
+}
+export interface HealthResult {
+    status: string;
+    engine: string;
+    engineStatus: string;
+    engineScore: number;
+    engineSize: string;
+    [key: string]: unknown;
+}
+export interface InfoResult {
+    name: string;
+    version: string;
+    [key: string]: unknown;
+}
+export declare class MCPaaS {
+    private baseUrl;
+    constructor(options?: MCPaaSOptions);
+    /** Fetch structured soul content by name */
+    getSoul(name: string): Promise<string>;
+    /** Fetch raw plain-text soul content */
+    getRawSoul(name: string): Promise<string>;
+    /** Get soul stats (counts, top souls, operations) */
+    listSouls(): Promise<SoulStats>;
+    /** Score a namepoint by handle */
+    score(handle: string): Promise<ScoreResult>;
+    /** Score a GitHub repo (owner/repo or full URL) */
+    scoreRepo(repo: string): Promise<RepoScore>;
+    /** Get the scoring leaderboard */
+    leaderboard(): Promise<LeaderboardResult>;
+    /** Get the full namepoint directory */
+    directory(): Promise<DirectoryResult>;
+    /** Check if a handle is available */
+    check(handle: string): Promise<CheckResult>;
+    /** Get namepoint counts */
+    count(): Promise<CountResult>;
+    /** Discovery feed (namepoints + souls) */
+    discover(): Promise<DiscoverResult>;
+    /** Full tag intelligence: patterns, co-occurrence, candidates, merges */
+    tagIntel(): Promise<TagIntelResult>;
+    /** Suggest tags for a namepoint based on content patterns */
+    suggestTags(handle: string): Promise<SuggestResult>;
+    /** Get the badge URL for a GitHub repo (synchronous — returns URL string) */
+    badge(owner: string, repo: string): string;
+    /** Get edge location execution stats from 300+ Cloudflare colos */
+    globe(): Promise<GlobeResult>;
+    /** Health check */
+    health(): Promise<HealthResult>;
+    /** Server info */
+    info(): Promise<InfoResult>;
+    private json;
+    private text;
+}
+export declare class MCPaaSError extends Error {
+    status: number;
+    body: string;
+    path: string;
+    constructor(status: number, body: string, path: string);
+}
+export default MCPaaS;