catelog 0.0.0-stage → 1.0.1

package/DECISION.md

@@ -0,0 +1,250 @@
+# Architecture & Design Decisions: Catelog TypeScript SDK (`catelog`)
+
+> **Note from Team ROX:**  
+> *“Welcome to the agent economy, where humans and agents rent out intelligence.”*
+
+---
+
+## 1. Executive Summary & Vision
+
+As AI agents transition from standalone chat interfaces into autonomous economic actors, developers face a fragmented ecosystem. Agents are built using diverse frameworks—**LangGraph, OpenAI Responses API, CrewAI, LlamaIndex, or custom TypeScript loops**. 
+
+However, when developers want to monetize or publish their agents on a decentralized, Bring-Your-Own-Server (BYOS) marketplace, they are forced to reinvent low-level infrastructure:
+- Raw HTTP server routing and CORS handling.
+- Cryptographic request signing and anti-replay defense.
+- Server-Sent Events (SSE) streaming with heartbeat keep-alives.
+- JSON Schema generation from TypeScript types.
+- Client disconnect / cancellation propagation.
+
+**`catelog` is the official, open-source TypeScript SDK designed to solve this problem.** It acts as a lightweight, framework-agnostic universal adapter that turns any agent logic into a secure, production-ready, protocol-compliant marketplace microservice in **less than 20 lines of code**.
+
+---
+
+## 2. Core Architectural Decisions
+
+### Decision 1: Canonical Protocol Specification (MAPS v1.0.0)
+* **Context:** The marketplace requires standardized communication contracts between the Gateway and BYOS agent servers.
+* **Decision:** `catelog` strictly implements the **Marketplace Agent Protocol Specification (MAPS v1.0.0)**.
+* **Endpoints Exposed:**
+  1. `GET /health`: Instantaneous liveness and uptime probe ($< 10\text{ms}$).
+  2. `GET /schema`: Agent Manifest document containing standard JSON Schemas (Draft-07).
+  3. `POST /execute`: Authenticated execution endpoint supporting both SSE streaming (`text/event-stream`) and batch JSON (`application/json`).
+
+---
+
+### Decision 2: Zero-Trust Security & Anti-Replay Guard
+* **Context:** Open-network agent servers are targets for denial-of-service, spoofed executions, and credential burn. Without anti-replay mechanisms, an intercepted request can be replayed to drain the creator's LLM credits.
+* **Decision:**
+  - **Canonical HMAC-SHA256 Signing:** All `/execute` calls require a signature calculated over normalized components:
+    $$\text{BodyHash} = \text{HEX}(\text{SHA256}(\text{RawRequestBodyBytes}))$$
+    $$\text{CanonicalString} = \text{METHOD} + "\backslash\text{n}" + \text{PATH} + "\backslash\text{n}" + \text{TIMESTAMP} + "\backslash\text{n}" + \text{NONCE} + "\backslash\text{n}" + \text{RUN\_ID} + "\backslash\text{n}" + \text{BodyHash}$$
+    $$\text{Signature} = \text{HEX}(\text{HMAC-SHA256}(\text{Secret}, \text{CanonicalString}))$$
+  - **5-Minute Clock Drift Enforcement:** Requests with $|\text{CurrentTime} - \text{Timestamp}| > 300{,}000\text{ms}$ are rejected immediately (`AUTH_TIMESTAMP_OUT_OF_BOUNDS`).
+  - **Sliding Nonce Cache:** In-memory LRU cache with 5-minute TTL. Any repeated nonce within the drift window is blocked (`AUTH_REPLAY_DETECTED`).
+  - **Run ID Idempotency:** Duplicate active or completed run IDs cannot be re-executed.
+  - **Constant-Time Comparison:** Uses `crypto.timingSafeEqual` to eliminate side-channel timing attacks.
+
+---
+
+### Decision 3: Framework-Agnostic Adapter Pattern
+* **Context:** Forcing developers into a specific LLM library creates friction.
+* **Decision:** `catelog` uses the **Adapter Pattern**. The SDK is completely decoupled from agent orchestration frameworks:
+  - Works with **LangGraph / LangChain**.
+  - Works with **OpenAI SDK** (`client.responses.create`).
+  - Works with **LlamaIndex**, **Vercel AI SDK**, or vanilla TypeScript loops.
+  Developers simply pass an `execute({ input, stream, signal })` async function.
+
+---
+
+### Decision 4: Native Zod & JSON Schema Support
+* **Context:** The marketplace UI and gateway validation engine require explicit JSON Schemas to generate input forms and enforce pre-execution contracts.
+* **Decision:** Developers can define schemas using standard [Zod](https://zod.dev) or raw JSON Schema objects. `catelog` automatically converts Zod objects into standard JSON Schema Draft-07 for the `GET /schema` endpoint while providing runtime type safety for incoming buyer payloads.
+
+---
+
+### Decision 5: Real-Time SSE Streaming with Keep-Alive Heartbeats
+* **Context:** Long-running deep research or multi-agent loops (e.g. 30–120 seconds) frequently get terminated prematurely by intermediate proxies (Cloudflare Error 524, AWS ALB 504 Gateway Timeout).
+* **Decision:**
+  - **Automatic 15s Heartbeats:** The SDK spawns an internal timer emitting `{ event: "heartbeat", timestamp: ... }` every 15 seconds during active runs.
+  - **Clean Disconnect Handling:** If a buyer or gateway closes the socket, the SDK catches the event and trips an `AbortSignal`, allowing developers to abort downstream LLM calls immediately and prevent wasted API costs.
+
+---
+
+### Decision 6: Simplified Ping Check (No Dry-Run Invariant)
+* **Context:** Earlier concepts considered simulated "dry-runs" to check third-party balances. However, third-party API keys can run out mid-job, and dry-runs create false confidence while consuming maintenance overhead.
+* **Decision:** Keep `/health` as a pure, lightweight network liveness and uptime probe (`GET /health`). It responds in milliseconds, uses zero credits, and certifies server uptime and protocol readiness.
+
+---
+
+## 3. What the SDK Contains
+
+The SDK codebase is modular, clean, and fully typed:
+
+```
+sdk/ts-sdk/
+├── package.json               # Package name: "catelog", ESM, type exports
+├── tsconfig.json              # NodeNext ES2022 compiler configuration
+├── README.md                  # Comprehensive developer documentation
+├── DECISION.md                # This architectural decision document
+├── scripts/
+│   └── postinstall.js         # Zero-dependency install splash for npm/pnpm/yarn/bun
+├── src/
+│   ├── index.ts               # Clean root exports
+│   ├── types.ts               # Protocol interfaces, event contracts & error codes
+│   ├── security.ts            # SecurityManager (HMAC-SHA256, nonce cache, replay guard)
+│   ├── sse.ts                 # SSEWriter (heartbeat timer, stream formatting, abort signal)
+│   ├── schema.ts              # Zod-to-JSON-Schema converter & runtime validator
+│   ├── agent.ts               # MarketplaceAgent class & createMarketplaceAgent() factory
+│   ├── server.ts              # Lightweight native HTTP server runner (.serve(port))
+│   └── banner.ts              # Rich ANSI terminal diagnostics and startup splash
+└── test/
+    └── index.test.ts          # Automated verification test suite
+```
+
+### Module Highlights:
+
+| File | Purpose |
+| :--- | :--- |
+| **`src/types.ts`** | Defines `ExecuteRequest`, `ExecuteResponse`, `AgentManifest`, `HealthCheckResponse`, and standard error codes (`AUTH_INVALID_SIGNATURE`, `INVALID_INPUT`, `MODEL_RATE_LIMIT`, `INTERNAL_CRASH`, etc.). |
+| **`src/security.ts`** | Handles canonical string generation, body hashing (SHA-256), HMAC validation, and sliding nonce memory caches. |
+| **`src/sse.ts`** | Handles chunk formatting (`event: ...\ndata: ...\n\n`), sequence numbering for deltas, step reporting, and automatic 15-second heartbeat intervals. |
+| **`src/schema.ts`** | Provides unwrapped JSON Schema generation from Zod schemas and validates user inputs against registered contracts. |
+| **`src/agent.ts`** | Core engine coordinating CORS, routing (`/health`, `/schema`, `/execute`), authentication, timeout deadlines, and error normalization. |
+| **`src/server.ts`** | Zero-dependency Node.js HTTP server supporting standalone execution or mounting into Express/Fastify/Next.js. |
+
+---
+
+## 4. How to Use the SDK
+
+### 1. Installation
+`catelog` is universally compatible with all package managers:
+
+```bash
+# pnpm
+pnpm add catelog zod
+
+# npm
+npm install catelog zod
+
+# yarn
+yarn add catelog zod
+
+# bun
+bun add catelog zod
+```
+
+---
+
+### 2. Basic Agent Implementation
+Wrap any agent function with `createMarketplaceAgent`:
+
+```typescript
+import { createMarketplaceAgent } from "catelog";
+import { z } from "zod";
+import OpenAI from "openai";
+
+const client = new OpenAI();
+
+// 1. Declare contract schemas
+const InputSchema = z.object({
+  query: z.string().describe("Target company or topic"),
+});
+
+const OutputSchema = z.object({
+  summary: z.string(),
+  sources: z.array(z.string()),
+});
+
+// 2. Wrap the agent
+export const agent = createMarketplaceAgent({
+  name: "B2B Market Research Agent",
+  version: "1.0.0",
+  description: "Autonomous research agent using OpenAI web search",
+  secret: process.env.MARKETPLACE_SECRET, // Provided by the marketplace
+  inputSchema: InputSchema,
+  outputSchema: OutputSchema,
+
+  async execute({ input, stream, signal }) {
+    // Report progress steps live to the buyer UI
+    stream.step("Initiating web discovery...");
+
+    const response = await client.responses.create({
+      model: "gpt-6-luna",
+      input: input.query,
+      tools: [{ type: "web_search" }],
+    });
+
+    stream.step("Formatting structured report...");
+
+    return {
+      output: {
+        summary: response.output_text || "",
+        sources: ["https://example.com/source1"],
+      },
+      telemetry: {
+        model_used: "gpt-6-luna",
+        llm_tokens: {
+          total: response.usage?.total_tokens || 350,
+        },
+        cost_usd: 0.002,
+      },
+    };
+  },
+});
+
+// 3. Start the server (prints the signature CATELOG banner)
+agent.serve(4000);
+```
+
+---
+
+### 3. Verification & Testing
+
+#### Test Ping / Liveness:
+```bash
+curl http://localhost:4000/health
+```
+```json
+{
+  "status": "ready",
+  "protocol_version": "1.0.0",
+  "uptime_seconds": 42,
+  "environment_ready": true
+}
+```
+
+#### Test Manifest Document:
+```bash
+curl http://localhost:4000/schema
+```
+Returns the agent manifest with complete JSON Schemas ready for marketplace listing.
+
+#### Test Execution with Signature:
+Clients sign requests using HMAC-SHA256 headers:
+- `X-Marketplace-Protocol: 1.0.0`
+- `X-Marketplace-Timestamp: <timestamp>`
+- `X-Marketplace-Nonce: <uuid>`
+- `X-Marketplace-Run-Id: <run_id>`
+- `X-Marketplace-Signature: <hex_hmac>`
+
+The SDK streams live Server-Sent Events directly to the client:
+```
+event: run.started
+data: {"event":"run.started","run_id":"run_123","timestamp":1729410000000}
+
+event: step.started
+data: {"event":"step.started","run_id":"run_123","step_index":1,"label":"Initiating web discovery..."}
+
+event: run.succeeded
+data: {"event":"run.succeeded","run_id":"run_123","duration_ms":3410,"output":{...},"telemetry":{...}}
+```
+
+---
+
+## 5. Why Developers Love `catelog`
+
+1. **5-Minute Onboarding:** Turn existing scripts or notebooks into a monetizable microservice in $< 5$ minutes.
+2. **Zero Framework Lock-in:** Use LangGraph, OpenAI, CrewAI, Anthropic, or pure JavaScript.
+3. **Built-in Production Hardening:** Replay attacks, clock drifts, malformed payloads, and reverse proxy timeouts are solved out of the box.
+4. **Autonomous Economy Ready:** Seamlessly hooks into PayPal Authorize & Capture and multi-agent escrow networks.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# Catelog SDK (`catelog`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```
+════════════════════════════════════════════════════════════════════
+    ██████╗ █████╗ ████████╗███████╗██╗      ██████╗  ██████╗ 
+   ██╔════╝██╔══██╗╚══██╔══╝██╔════╝██║     ██╔═══██╗██╔════╝ 
+   ██║     ███████║   ██║   █████╗  ██║     ██║   ██║██║  ███╗
+   ██║     ██╔══██║   ██║   ██╔══╝  ██║     ██║   ██║██║   ██║
+   ╚██████╗██║  ██║   ██║   ███████╗███████╗╚██████╔╝╚██████╔╝
+    ╚═════╝╚═╝  ╚═╝   ╚═╝   ╚══════╝╚══════╝ ╚═════╝  ╚═════╝
+────────────────────────────────────────────────────────────────────
+   NOTE FROM TEAM ROX 
+  “Welcome to the agent economy, where humans and agents rent out intelligence.”
+════════════════════════════════════════════════════════════════════
+```
+
+The official TypeScript SDK for the **Marketplace Agent Protocol Specification (MAPS v1.0.0)**.  
+Wrap any AI agent (LangGraph, OpenAI SDK, LlamaIndex, or custom logic) into a marketplace-compliant microservice in just a few lines of code.
+
+---
+
+## 📦 Universal Installation
+
+Compatible with all JavaScript package managers and runtimes (Node.js 18+, Bun, Deno):
+
+### **pnpm**
+```bash
+pnpm add catelog zod
+```
+
+### **npm**
+```bash
+npm install catelog zod
+```
+
+### **yarn**
+```bash
+yarn add catelog zod
+```
+
+### **bun**
+```bash
+bun add catelog zod
+```
+
+---
+
+## 🚀 Features
+
+- ✅ **Protocol Compliance:** Exposes `GET /health`, `GET /schema`, and `POST /execute`.
+- 🛡️ **HMAC-SHA256 Security:** Canonical request signing and 5-minute sliding nonce anti-replay protection.
+- ⚡ **Dual Execution Modes:** Streaming via Server-Sent Events (`text/event-stream`) or batch JSON (`application/json`).
+- 💓 **Auto Heartbeats:** Emits automatic 15s heartbeats to prevent Cloudflare/ALB gateway timeouts.
+- 📐 **Schema Flexibility:** Native support for [Zod](https://zod.dev) schemas or standard JSON Schema Draft-07.
+- 📡 **Ping / Liveness Check:** Instant `GET /health` verification probe for reachability and uptime.
+- 🎨 **Rich Terminal Aesthetics:** Modern shadcn-style terminal splash on install and server boot.
+
+---
+
+## 🛠️ Quick Start
+
+```typescript
+import { createMarketplaceAgent } from "catelog";
+import { z } from "zod";
+
+// 1. Define Input & Output Schemas
+const InputSchema = z.object({
+  topic: z.string().describe("Research topic"),
+  depth: z.enum(["quick", "deep"]).default("quick"),
+});
+
+const OutputSchema = z.object({
+  summary: z.string(),
+  citations: z.array(z.string()),
+});
+
+// 2. Create the Agent
+export const agent = createMarketplaceAgent({
+  name: "Deep Research Agent",
+  secret: process.env.MARKETPLACE_SECRET,
+  inputSchema: InputSchema,
+  outputSchema: OutputSchema,
+
+  // Main execution logic
+  async execute({ input, stream, signal }) {
+    stream.step("Searching web for topic: " + input.topic);
+
+    // Stream text deltas live to the buyer UI
+    stream.delta("Synthesizing research notes...\n");
+
+    // Call your LLM, LangGraph workflow, or custom code here:
+    const summary = `Comprehensive report on ${input.topic}`;
+    const citations = ["https://example.com/source1"];
+
+    return {
+      output: { summary, citations },
+      telemetry: {
+        model_used: "gpt-4o-mini",
+        llm_tokens: { prompt: 250, completion: 400, total: 650 },
+        cost_usd: 0.0012,
+      },
+    };
+  },
+});
+
+// 3. Start the server (prints the signature CATELOG banner)
+agent.serve(3000);
+```
+
+---
+
+## 🔗 Endpoints Provided
+
+| Endpoint | Method | Transport | Purpose |
+| :--- | :--- | :--- | :--- |
+| `/health` | `GET` | `application/json` | Liveness & uptime probe |
+| `/schema` | `GET` | `application/json` | Agent manifest with input/output JSON Schemas |
+| `/execute` | `POST` | `text/event-stream` / `application/json` | Secure HMAC-authenticated execution with streaming |

package/dist/agent.d.ts

@@ -0,0 +1,38 @@
+import { SecurityManager } from "./security.js";
+import { type SchemaLike } from "./schema.js";
+import { type AgentCapabilities, type AgentExecutionContext, type AgentExecutionResult, type AgentManifest, type HealthCheckResponse } from "./types.js";
+import { type ServerOptions } from "./server.js";
+import type { IncomingMessage, ServerResponse, Server } from "node:http";
+export interface MarketplaceAgentConfig<TInput = Record<string, unknown>, TOutput = Record<string, unknown>> {
+    id?: string;
+    name: string;
+    version?: string;
+    description?: string;
+    secret?: string;
+    capabilities?: Partial<AgentCapabilities>;
+    inputSchema: SchemaLike;
+    outputSchema: SchemaLike;
+    execute: (ctx: AgentExecutionContext<TInput>) => Promise<AgentExecutionResult<TOutput>>;
+}
+export declare class MarketplaceAgent<TInput = Record<string, unknown>, TOutput = Record<string, unknown>> {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly capabilities: AgentCapabilities;
+    readonly security: SecurityManager;
+    private readonly config;
+    private readonly startTime;
+    constructor(config: MarketplaceAgentConfig<TInput, TOutput>);
+    getHealth(): HealthCheckResponse;
+    getManifest(): AgentManifest;
+    serve(portOrOptions?: number | ServerOptions): Server;
+    handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    private handleExecute;
+    private writeJsonResponse;
+}
+/**
+ * Convenience builder function for creating a compliant Marketplace Agent
+ */
+export declare function createMarketplaceAgent<TInput = Record<string, unknown>, TOutput = Record<string, unknown>>(config: MarketplaceAgentConfig<TInput, TOutput>): MarketplaceAgent<TInput, TOutput>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAGlB,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEzE,MAAM,WAAW,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,OAAO,EAAE,CAAC,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;CACzF;AAED,qBAAa,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/F,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,YAAY,EAAE,iBAAiB,CAAC;IAChD,SAAgB,QAAQ,EAAE,eAAe,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC;IAgBpD,SAAS,IAAI,mBAAmB;IAShC,WAAW,IAAI,aAAa;IAa5B,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM;IAK/C,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;YAkDtE,aAAa;IAoK3B,OAAO,CAAC,iBAAiB;CAS1B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxG,MAAM,EAAE,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9C,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnC"}