@basedchef/contextkit 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# contextkit TypeScript SDK
+
+Typed SDK for ContextKit, the x402-powered context infrastructure API for AI agents.
+
+```ts
+import { ContextKit } from "contextkit";
+
+const client = new ContextKit({
+  apiKey: process.env.CONTEXTKIT_API_KEY!,
+  x402: async (challenge) => wallet.pay(challenge)
+});
+
+const response = await client.summarize({ messages });
+```
+
+## Methods
+
+- `summarize(request)`
+- `compressContext(request)`
+- `handoff(request)`
+- `extractProfile(request)`
+- `estimateTokens(request)`
+
+## Webhook Verification
+
+```ts
+import { verifyContextKitWebhook } from "contextkit";
+
+const valid = await verifyContextKitWebhook({
+  payload: rawBody,
+  signature: request.headers.get("ContextKit-Signature")!,
+  secret: process.env.CONTEXTKIT_WEBHOOK_SECRET!
+});
+```
+
+## Build
+
+```bash
+npm install
+npm run build
+```

package/dist/index.cjs

@@ -0,0 +1,146 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ContextKit: () => ContextKit,
+  ContextKitError: () => ContextKitError,
+  encodeX402Payment: () => encodeX402Payment,
+  getFirstX402Requirement: () => getFirstX402Requirement,
+  verifyContextKitWebhook: () => verifyContextKitWebhook
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var ContextKit = class {
+  constructor(options) {
+    this.options = options;
+    this.baseUrl = options.baseUrl ?? "https://contextkit.dev";
+    this.fetcher = options.fetch ?? fetch;
+    this.retries = options.retries ?? 2;
+    this.x402 = options.x402;
+  }
+  options;
+  baseUrl;
+  fetcher;
+  retries;
+  x402;
+  summarize(request) {
+    return this.post("/api/summarize", request);
+  }
+  compressContext(request) {
+    return this.post("/api/compress-context", request);
+  }
+  handoff(request) {
+    return this.post("/api/handoff", request);
+  }
+  extractProfile(request) {
+    return this.post("/api/extract-profile", request);
+  }
+  memoryEnrichment(request) {
+    return this.post("/api/memory-enrichment", request);
+  }
+  async estimateTokens(input) {
+    return this.post("/api/tokens/estimate", input);
+  }
+  async post(path, body) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}${path}`;
+    const init = {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.options.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    };
+    for (let attempt = 0; attempt <= this.retries; attempt += 1) {
+      const response = await this.fetcher(url, init);
+      if (response.status === 402 && this.x402) {
+        const challenge = await response.json();
+        const payment = await this.x402(challenge, { ...init, url });
+        init.headers = { ...init.headers, "X-Payment": payment };
+        continue;
+      }
+      if (response.ok) {
+        return await response.json();
+      }
+      if (response.status >= 500 && attempt < this.retries) {
+        await delay(2 ** attempt * 250);
+        continue;
+      }
+      throw new ContextKitError(response.status, await response.text());
+    }
+    throw new Error("ContextKit request failed after retries.");
+  }
+};
+var ContextKitError = class extends Error {
+  constructor(status, body) {
+    super(`ContextKit API request failed with ${status}: ${body}`);
+    this.status = status;
+    this.body = body;
+  }
+  status;
+  body;
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/webhooks.ts
+async function verifyContextKitWebhook(input) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(input.secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const digest = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(input.payload));
+  const expected = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return timingSafeEqual(expected, input.signature);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    result |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return result === 0;
+}
+
+// src/x402.ts
+function getFirstX402Requirement(challenge) {
+  const requirement = challenge.accepts?.[0];
+  if (!requirement) {
+    throw new Error("ContextKit response did not include an x402 payment requirement.");
+  }
+  return requirement;
+}
+function encodeX402Payment(payment) {
+  return typeof payment === "string" ? payment : JSON.stringify(payment);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ContextKit,
+  ContextKitError,
+  encodeX402Payment,
+  getFirstX402Requirement,
+  verifyContextKitWebhook
+});

package/dist/index.d.cts

@@ -0,0 +1,256 @@
+type Role = "system" | "user" | "assistant" | "tool";
+type ConversationMessage = {
+    role: Role;
+    content: string;
+};
+type ContextRequest = {
+    messages: ConversationMessage[];
+    mode?: "micro" | "compact" | "extended" | "debug";
+    metadata?: Record<string, unknown>;
+    webhookUrl?: string;
+};
+type SummarizeResponse = {
+    mode: "micro" | "compact" | "extended" | "debug";
+    summary?: string;
+    micro?: string;
+    compact?: string;
+    extended?: string;
+    state: {
+        goal: string;
+        status: string;
+        blockers: string[];
+        next: string[];
+    };
+    keyDecisions?: string[];
+    actionItems?: string[];
+    openQuestions?: string[];
+    risks?: string[];
+    metrics: {
+        inputTokens: number;
+        compactTokens: number;
+        stateTokens: number;
+        totalOutputTokens: number;
+        reductionPercent: number;
+        latencyMs: number;
+    };
+    confidence?: number;
+};
+type CompressContextResponse = {
+    compressedContext: string;
+    state: {
+        goals: string[];
+        status: string[];
+        activeProblems: string[];
+        constraints: string[];
+        decisions: string[];
+        nextSteps: string[];
+    };
+    entities: {
+        people: string[];
+        projects: string[];
+        technologies: string[];
+        organizations: string[];
+        deadlines: string[];
+    };
+    conflicts?: Array<{
+        old: string;
+        new: string;
+    }>;
+    metrics: {
+        inputTokens: number;
+        compressedTokens: number;
+        reductionPercent: number;
+    };
+};
+type HandoffResponse = {
+    project: {
+        name: string;
+        goal: string;
+        currentState: string;
+    };
+    completed: string[];
+    inProgress: string[];
+    pending: string[];
+    blockers: string[];
+    failedApproaches: Array<{
+        attempt: string;
+        result: string;
+        lesson: string;
+    }>;
+    decisions: Array<{
+        decision: string;
+        reason: string;
+    }>;
+    priorities: string[];
+    criticalContext: {
+        mustKnow: string[];
+        mustNotDo: string[];
+        biggestRisk: string;
+        successMetric: string;
+    };
+    startHere: string;
+    agentNotes: string[];
+};
+type ProfileResponse = {
+    mode: "micro" | "compact" | "full";
+    micro: {
+        identity: {
+            profession?: string;
+            location?: string;
+            age?: number | null;
+        };
+        preferences: string[];
+        goals: string[];
+    };
+    compact: {
+        identity: {
+            profession?: string;
+            location?: string;
+            age?: number | null;
+        };
+        skills: string[];
+        interests: string[];
+        preferences: string[];
+        goals: string[];
+        traits: string[];
+    };
+    full: {
+        identity: {
+            profession?: string;
+            location?: string;
+            age?: number | null;
+        };
+        skills: string[];
+        interests: string[];
+        stablePreferences: string[];
+        currentGoals: string[];
+        futurePlans: string[];
+        inferredTraits: string[];
+        stableMemories: string[];
+        evolvingMemories: string[];
+    };
+    memoryFacts: Array<{
+        fact: string;
+        category: string;
+        stability: "stable" | "evolving";
+        confidence: number;
+    }>;
+    interests: string[];
+    riskTolerance: string;
+    communicationStyle: string;
+    preferences: string[];
+    importantContext: string[];
+    identity: {
+        profession?: string;
+        location?: string;
+        age?: number | null;
+    };
+    skills: string[];
+    goals: string[];
+    futurePlans: string[];
+    behaviorPatterns: string[];
+    dislikes: string[];
+    careerStage: string;
+    managementIntent: boolean;
+    entrepreneurial: boolean;
+    inferredTraits: string[];
+    memoryImportance: number;
+    stableMemories: string[];
+    evolvingMemories: string[];
+    deprecatedMemories: string[];
+    confidence: number;
+};
+type MemoryEnrichmentResponse = {
+    activeMemories: Array<{
+        fact: string;
+        category: string;
+        stability: "stable";
+        confidence: number;
+    }>;
+    evolvingMemories: Array<{
+        fact: string;
+        category: string;
+        stability: "evolving";
+        confidence: number;
+    }>;
+    conflicts: Array<{
+        old: string;
+        new: string;
+        reason: string;
+    }>;
+    stablePreferences: string[];
+    evolvingPreferences: string[];
+    longTermGoals: string[];
+    supersededMemories: string[];
+    memoryConflicts: Array<{
+        current: string;
+        superseded: string[];
+    }>;
+    stableMemories: string[];
+    legacyEvolvingMemories?: string[];
+    deprecatedMemories: string[];
+    confidence: number;
+};
+type X402PaymentHandler = (challenge: unknown, request: RequestInit & {
+    url: string;
+}) => Promise<string>;
+
+type ContextKitOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    retries?: number;
+    x402?: X402PaymentHandler;
+};
+declare class ContextKit {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetcher;
+    private readonly retries;
+    private readonly x402?;
+    constructor(options: ContextKitOptions);
+    summarize(request: ContextRequest): Promise<SummarizeResponse>;
+    compressContext(request: ContextRequest): Promise<CompressContextResponse>;
+    handoff(request: ContextRequest): Promise<HandoffResponse>;
+    extractProfile(request: ContextRequest): Promise<ProfileResponse>;
+    memoryEnrichment(request: ContextRequest): Promise<MemoryEnrichmentResponse>;
+    estimateTokens(input: unknown): Promise<{
+        inputTokens: number;
+        compressedTokens: number;
+        reductionPercent: number;
+    }>;
+    private post;
+}
+declare class ContextKitError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+
+declare function verifyContextKitWebhook(input: {
+    payload: string;
+    signature: string;
+    secret: string;
+}): Promise<boolean>;
+
+type X402Challenge = {
+    accepts?: Array<{
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        resource: string;
+        payTo: string;
+        asset: string;
+    }>;
+};
+declare function getFirstX402Requirement(challenge: X402Challenge): {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    payTo: string;
+    asset: string;
+};
+declare function encodeX402Payment(payment: unknown): string;
+
+export { type CompressContextResponse, ContextKit, ContextKitError, type ContextRequest, type ConversationMessage, type HandoffResponse, type MemoryEnrichmentResponse, type ProfileResponse, type SummarizeResponse, type X402PaymentHandler, encodeX402Payment, getFirstX402Requirement, verifyContextKitWebhook };

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+type Role = "system" | "user" | "assistant" | "tool";
+type ConversationMessage = {
+    role: Role;
+    content: string;
+};
+type ContextRequest = {
+    messages: ConversationMessage[];
+    mode?: "micro" | "compact" | "extended" | "debug";
+    metadata?: Record<string, unknown>;
+    webhookUrl?: string;
+};
+type SummarizeResponse = {
+    mode: "micro" | "compact" | "extended" | "debug";
+    summary?: string;
+    micro?: string;
+    compact?: string;
+    extended?: string;
+    state: {
+        goal: string;
+        status: string;
+        blockers: string[];
+        next: string[];
+    };
+    keyDecisions?: string[];
+    actionItems?: string[];
+    openQuestions?: string[];
+    risks?: string[];
+    metrics: {
+        inputTokens: number;
+        compactTokens: number;
+        stateTokens: number;
+        totalOutputTokens: number;
+        reductionPercent: number;
+        latencyMs: number;
+    };
+    confidence?: number;
+};
+type CompressContextResponse = {
+    compressedContext: string;
+    state: {
+        goals: string[];
+        status: string[];
+        activeProblems: string[];
+        constraints: string[];
+        decisions: string[];
+        nextSteps: string[];
+    };
+    entities: {
+        people: string[];
+        projects: string[];
+        technologies: string[];
+        organizations: string[];
+        deadlines: string[];
+    };
+    conflicts?: Array<{
+        old: string;
+        new: string;
+    }>;
+    metrics: {
+        inputTokens: number;
+        compressedTokens: number;
+        reductionPercent: number;
+    };
+};
+type HandoffResponse = {
+    project: {
+        name: string;
+        goal: string;
+        currentState: string;
+    };
+    completed: string[];
+    inProgress: string[];
+    pending: string[];
+    blockers: string[];
+    failedApproaches: Array<{
+        attempt: string;
+        result: string;
+        lesson: string;
+    }>;
+    decisions: Array<{
+        decision: string;
+        reason: string;
+    }>;
+    priorities: string[];
+    criticalContext: {
+        mustKnow: string[];
+        mustNotDo: string[];
+        biggestRisk: string;
+        successMetric: string;
+    };
+    startHere: string;
+    agentNotes: string[];
+};
+type ProfileResponse = {
+    mode: "micro" | "compact" | "full";
+    micro: {
+        identity: {
+            profession?: string;
+            location?: string;
+            age?: number | null;
+        };
+        preferences: string[];
+        goals: string[];
+    };
+    compact: {
+        identity: {
+            profession?: string;
+            location?: string;
+            age?: number | null;
+        };
+        skills: string[];
+        interests: string[];
+        preferences: string[];
+        goals: string[];
+        traits: string[];
+    };
+    full: {
+        identity: {
+            profession?: string;
+            location?: string;
+            age?: number | null;
+        };
+        skills: string[];
+        interests: string[];
+        stablePreferences: string[];
+        currentGoals: string[];
+        futurePlans: string[];
+        inferredTraits: string[];
+        stableMemories: string[];
+        evolvingMemories: string[];
+    };
+    memoryFacts: Array<{
+        fact: string;
+        category: string;
+        stability: "stable" | "evolving";
+        confidence: number;
+    }>;
+    interests: string[];
+    riskTolerance: string;
+    communicationStyle: string;
+    preferences: string[];
+    importantContext: string[];
+    identity: {
+        profession?: string;
+        location?: string;
+        age?: number | null;
+    };
+    skills: string[];
+    goals: string[];
+    futurePlans: string[];
+    behaviorPatterns: string[];
+    dislikes: string[];
+    careerStage: string;
+    managementIntent: boolean;
+    entrepreneurial: boolean;
+    inferredTraits: string[];
+    memoryImportance: number;
+    stableMemories: string[];
+    evolvingMemories: string[];
+    deprecatedMemories: string[];
+    confidence: number;
+};
+type MemoryEnrichmentResponse = {
+    activeMemories: Array<{
+        fact: string;
+        category: string;
+        stability: "stable";
+        confidence: number;
+    }>;
+    evolvingMemories: Array<{
+        fact: string;
+        category: string;
+        stability: "evolving";
+        confidence: number;
+    }>;
+    conflicts: Array<{
+        old: string;
+        new: string;
+        reason: string;
+    }>;
+    stablePreferences: string[];
+    evolvingPreferences: string[];
+    longTermGoals: string[];
+    supersededMemories: string[];
+    memoryConflicts: Array<{
+        current: string;
+        superseded: string[];
+    }>;
+    stableMemories: string[];
+    legacyEvolvingMemories?: string[];
+    deprecatedMemories: string[];
+    confidence: number;
+};
+type X402PaymentHandler = (challenge: unknown, request: RequestInit & {
+    url: string;
+}) => Promise<string>;
+
+type ContextKitOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    retries?: number;
+    x402?: X402PaymentHandler;
+};
+declare class ContextKit {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetcher;
+    private readonly retries;
+    private readonly x402?;
+    constructor(options: ContextKitOptions);
+    summarize(request: ContextRequest): Promise<SummarizeResponse>;
+    compressContext(request: ContextRequest): Promise<CompressContextResponse>;
+    handoff(request: ContextRequest): Promise<HandoffResponse>;
+    extractProfile(request: ContextRequest): Promise<ProfileResponse>;
+    memoryEnrichment(request: ContextRequest): Promise<MemoryEnrichmentResponse>;
+    estimateTokens(input: unknown): Promise<{
+        inputTokens: number;
+        compressedTokens: number;
+        reductionPercent: number;
+    }>;
+    private post;
+}
+declare class ContextKitError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+
+declare function verifyContextKitWebhook(input: {
+    payload: string;
+    signature: string;
+    secret: string;
+}): Promise<boolean>;
+
+type X402Challenge = {
+    accepts?: Array<{
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        resource: string;
+        payTo: string;
+        asset: string;
+    }>;
+};
+declare function getFirstX402Requirement(challenge: X402Challenge): {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    payTo: string;
+    asset: string;
+};
+declare function encodeX402Payment(payment: unknown): string;
+
+export { type CompressContextResponse, ContextKit, ContextKitError, type ContextRequest, type ConversationMessage, type HandoffResponse, type MemoryEnrichmentResponse, type ProfileResponse, type SummarizeResponse, type X402PaymentHandler, encodeX402Payment, getFirstX402Requirement, verifyContextKitWebhook };

package/dist/index.js

@@ -0,0 +1,115 @@
+// src/client.ts
+var ContextKit = class {
+  constructor(options) {
+    this.options = options;
+    this.baseUrl = options.baseUrl ?? "https://contextkit.dev";
+    this.fetcher = options.fetch ?? fetch;
+    this.retries = options.retries ?? 2;
+    this.x402 = options.x402;
+  }
+  options;
+  baseUrl;
+  fetcher;
+  retries;
+  x402;
+  summarize(request) {
+    return this.post("/api/summarize", request);
+  }
+  compressContext(request) {
+    return this.post("/api/compress-context", request);
+  }
+  handoff(request) {
+    return this.post("/api/handoff", request);
+  }
+  extractProfile(request) {
+    return this.post("/api/extract-profile", request);
+  }
+  memoryEnrichment(request) {
+    return this.post("/api/memory-enrichment", request);
+  }
+  async estimateTokens(input) {
+    return this.post("/api/tokens/estimate", input);
+  }
+  async post(path, body) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}${path}`;
+    const init = {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.options.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    };
+    for (let attempt = 0; attempt <= this.retries; attempt += 1) {
+      const response = await this.fetcher(url, init);
+      if (response.status === 402 && this.x402) {
+        const challenge = await response.json();
+        const payment = await this.x402(challenge, { ...init, url });
+        init.headers = { ...init.headers, "X-Payment": payment };
+        continue;
+      }
+      if (response.ok) {
+        return await response.json();
+      }
+      if (response.status >= 500 && attempt < this.retries) {
+        await delay(2 ** attempt * 250);
+        continue;
+      }
+      throw new ContextKitError(response.status, await response.text());
+    }
+    throw new Error("ContextKit request failed after retries.");
+  }
+};
+var ContextKitError = class extends Error {
+  constructor(status, body) {
+    super(`ContextKit API request failed with ${status}: ${body}`);
+    this.status = status;
+    this.body = body;
+  }
+  status;
+  body;
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/webhooks.ts
+async function verifyContextKitWebhook(input) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(input.secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const digest = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(input.payload));
+  const expected = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return timingSafeEqual(expected, input.signature);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    result |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return result === 0;
+}
+
+// src/x402.ts
+function getFirstX402Requirement(challenge) {
+  const requirement = challenge.accepts?.[0];
+  if (!requirement) {
+    throw new Error("ContextKit response did not include an x402 payment requirement.");
+  }
+  return requirement;
+}
+function encodeX402Payment(payment) {
+  return typeof payment === "string" ? payment : JSON.stringify(payment);
+}
+export {
+  ContextKit,
+  ContextKitError,
+  encodeX402Payment,
+  getFirstX402Requirement,
+  verifyContextKitWebhook
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@basedchef/contextkit",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for ContextKit context infrastructure APIs.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}