cogspace 0.3.1

package/README.md

@@ -0,0 +1,109 @@
+# @cogspace/sdk
+
+Official TypeScript SDK for [Cogspace](https://cogspace.ai) — persistent knowledge layer for AI agents.
+
+## Install
+
+```bash
+npm install @cogspace/sdk
+# or
+pnpm add @cogspace/sdk
+# or
+bun add @cogspace/sdk
+```
+
+## Quickstart
+
+```typescript
+import { Cogspace } from "@cogspace/sdk";
+
+// Reads COGSPACE_API_KEY from environment automatically
+const cog = new Cogspace();
+const space = await cog.space("my-agent");
+
+// See what exists
+const files = await space.list("expertise");
+console.log(`${files.file_count} files`);
+
+// Add knowledge
+await space.add(
+  "expertise/retry.md",
+  "# Retry Patterns\nUse exponential backoff with jitter.",
+  "expertise",
+  "retry-patterns",
+  { confidence: 0.95 }
+);
+
+// Search
+const results = await space.search("retry logic", { limit: 5 });
+for (const item of results.results) {
+  console.log(`${item.path}: ${item.score}`);
+}
+
+// Retrieve a file
+const file = await space.retrieve("expertise/retry.md");
+console.log(file.content);
+
+// Delete
+await space.forget("expertise/retry.md");
+```
+
+## Works everywhere
+
+Native `fetch` — no dependencies. Works in Node 18+, Deno, Bun, Edge, browser.
+
+## API Reference
+
+### `new Cogspace(config?)`
+
+Reads `COGSPACE_API_KEY` from environment if `apiKey` not provided.
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey` | env `COGSPACE_API_KEY` | Your API key |
+| `baseUrl` | `https://platform.cogspace.ai` | Platform URL |
+| `timeout` | `30000` | Request timeout (ms) |
+| `maxRetries` | `3` | Retries on 429/5xx |
+
+### `cog.space(nameOrId)` → `SpaceClient`
+
+| Method | Description |
+|---|---|
+| `space.list(folder?)` | List files in folder |
+| `space.retrieve(path)` | Get one file |
+| `space.search(query, options?)` | Search all layers |
+| `space.add(path, content, layer, topic, options?)` | Add/update knowledge |
+| `space.forget(path)` | Delete from all layers |
+
+#### `add()` parameters
+
+```typescript
+space.add(
+  "expertise/retry.md",           // path
+  "# Retry\nUse backoff...",      // content
+  "expertise",                    // layer: "expertise" | "memory" | "root"
+  "retry-patterns",               // topic
+  {
+    confidence: 0.95,             // 0.0-1.0, default 0.9
+    relates_to: ["error.md"],     // related files
+  }
+)
+```
+
+## Errors
+
+```typescript
+import { AuthError, NotFoundError, LimitExceededError } from "@cogspace/sdk";
+
+try {
+  await space.search("query", { limit: 200 });
+} catch (err) {
+  if (err instanceof LimitExceededError) console.error("Max limit is 100");
+  if (err instanceof AuthError) console.error("Invalid API key");
+  if (err instanceof NotFoundError) console.error("Space not found");
+}
+```
+
+## Get an API key
+
+Sign in at [platform.cogspace.ai](https://platform.cogspace.ai) → **Settings → API keys** → **Create key**.

package/dist/index.cjs

@@ -0,0 +1,301 @@
+"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, {
+  AuthError: () => AuthError,
+  Cogspace: () => Cogspace,
+  CogspaceError: () => CogspaceError,
+  HttpClient: () => HttpClient,
+  LimitExceededError: () => LimitExceededError,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  SpaceClient: () => SpaceClient,
+  TimeoutError: () => TimeoutError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var CogspaceError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "CogspaceError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var AuthError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "AuthError";
+  }
+};
+var NotFoundError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "ServerError";
+  }
+};
+var TimeoutError = class extends CogspaceError {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var LimitExceededError = class extends CogspaceError {
+  constructor(message) {
+    super(message);
+    this.name = "LimitExceededError";
+  }
+};
+function raiseForStatus(status, body) {
+  const message = String(body.detail ?? body.message ?? `HTTP ${status}`);
+  const code = body.error;
+  if (status === 401) throw new AuthError(message, status);
+  if (status === 404) throw new NotFoundError(message, status);
+  if (status === 429) throw new RateLimitError(message, status);
+  if (status >= 500) throw new ServerError(message, status);
+  throw new CogspaceError(message, status, code);
+}
+
+// src/client.ts
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var HttpClient = class {
+  constructor(config = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env["COGSPACE_API_KEY"] : void 0;
+    const key = config.apiKey ?? envKey ?? "";
+    if (!key) {
+      throw new Error(
+        "API key is required. Pass apiKey: in config or set the COGSPACE_API_KEY environment variable."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (config.baseUrl ?? "https://platform.cogspace.ai").replace(/\/$/, "");
+    this.timeout = config.timeout ?? 3e4;
+    this.maxRetries = config.maxRetries ?? 3;
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": "cogspace-ts/0.2.0"
+    };
+  }
+  async request(method, path, body, params) {
+    let url = `${this.baseUrl}${path}`;
+    if (params && Object.keys(params).length > 0) {
+      url += "?" + new URLSearchParams(params).toString();
+    }
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      let response;
+      try {
+        response = await fetch(url, {
+          method,
+          headers: this.headers(),
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof Error && err.name === "AbortError") {
+          throw new TimeoutError(`Request timed out: ${path}`);
+        }
+        throw err;
+      }
+      clearTimeout(timer);
+      if (!RETRY_STATUSES.has(response.status)) {
+        if (response.status >= 400) {
+          let errBody = {};
+          try {
+            errBody = await response.json();
+          } catch {
+          }
+          raiseForStatus(response.status, errBody);
+        }
+        if (response.status === 204 || response.headers.get("content-length") === "0") {
+          return void 0;
+        }
+        return response.json();
+      }
+      if (attempt < this.maxRetries - 1) {
+        let wait = Math.pow(2, attempt) * 1e3;
+        const retryAfter = response.headers.get("Retry-After");
+        if (retryAfter) wait = parseFloat(retryAfter) * 1e3;
+        await new Promise((r) => setTimeout(r, wait));
+        let errBody = {};
+        try {
+          errBody = await response.json();
+        } catch {
+        }
+        lastError = new RateLimitError(String(errBody.detail ?? `HTTP ${response.status}`), response.status);
+      } else {
+        let errBody = {};
+        try {
+          errBody = await response.json();
+        } catch {
+        }
+        raiseForStatus(response.status, errBody);
+      }
+    }
+    throw lastError ?? new RateLimitError("Max retries exceeded");
+  }
+  get(path, params) {
+    return this.request("GET", path, void 0, params);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  delete(path, params) {
+    return this.request("DELETE", path, void 0, params);
+  }
+};
+
+// src/space.ts
+var MAX_LIMIT = 100;
+var SpaceClient = class {
+  constructor(client, spaceId) {
+    this.client = client;
+    this.spaceId = spaceId;
+  }
+  path(endpoint) {
+    return `/spaces/${this.spaceId}/${endpoint}`;
+  }
+  /**
+   * List all files in a folder.
+   * @param folder - Folder to list (e.g. "expertise"). Empty = entire space.
+   */
+  list(folder = "") {
+    return this.client.get(this.path("list"), { folder });
+  }
+  /**
+   * Retrieve a single file by path.
+   * @param path - Relative file path (e.g. "expertise/retry.md").
+   */
+  retrieve(path) {
+    return this.client.get(this.path("retrieve"), { path });
+  }
+  /**
+   * Search all layers (vectors + BM25 + knowledge graph).
+   * @param query - What to search for.
+   * @param options.limit - Max results. Default 10, max 100.
+   * @param options.layer - Optional filter: "expertise", "memory", or "root".
+   */
+  async search(query, options = {}) {
+    const limit = options.limit ?? 10;
+    if (limit > MAX_LIMIT) {
+      throw new LimitExceededError(`limit must be <= ${MAX_LIMIT}. Got: ${limit}`);
+    }
+    return this.client.post(this.path("search"), {
+      query,
+      limit,
+      layer: options.layer ?? null
+    });
+  }
+  /**
+   * Add or update knowledge. All layers updated automatically.
+   * @param path - Where to write (e.g. "expertise/retry.md").
+   * @param content - Markdown content.
+   * @param layer - "expertise", "memory", or "root".
+   * @param topic - Category/topic for this knowledge.
+   * @param options.confidence - How certain (0.0-1.0). Default 0.9.
+   * @param options.relates_to - Related file names.
+   */
+  add(path, content, layer, topic, options = {}) {
+    return this.client.post(this.path("add"), {
+      path,
+      content,
+      layer,
+      topic,
+      confidence: options.confidence ?? 0.9,
+      relates_to: options.relates_to ?? null,
+      agent_id: options.agent_id ?? "default"
+    });
+  }
+  /**
+   * Delete knowledge from all layers (cascading).
+   * @param path - Relative file path to delete.
+   */
+  forget(path) {
+    return this.client.delete(this.path("forget"), { path });
+  }
+};
+
+// src/index.ts
+var Cogspace = class {
+  constructor(config = {}) {
+    this.spaceCache = /* @__PURE__ */ new Map();
+    this.client = new HttpClient(config);
+  }
+  async resolveSpaceId(nameOrId) {
+    const cached = this.spaceCache.get(nameOrId);
+    if (cached) return cached;
+    const spaces = await this.client.get("/spaces");
+    for (const s of spaces) {
+      this.spaceCache.set(s.name, s.id);
+      this.spaceCache.set(s.id, s.id);
+      if (s.name === nameOrId || s.id === nameOrId) {
+        return s.id;
+      }
+    }
+    throw new NotFoundError(`Space not found: ${nameOrId}`);
+  }
+  /** Get a space-scoped client by name or ID. */
+  async space(nameOrId) {
+    const spaceId = await this.resolveSpaceId(nameOrId);
+    return new SpaceClient(this.client, spaceId);
+  }
+  /** List all your spaces. */
+  listSpaces() {
+    return this.client.get("/spaces");
+  }
+  /** Create a new space. */
+  createSpace(name) {
+    return this.client.post("/spaces", { name });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthError,
+  Cogspace,
+  CogspaceError,
+  HttpClient,
+  LimitExceededError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  SpaceClient,
+  TimeoutError
+});

package/dist/index.d.cts

@@ -0,0 +1,201 @@
+/** HTTP client for the Cogspace TypeScript SDK. Zero dependencies — native fetch. */
+interface ClientConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(config?: ClientConfig);
+    private headers;
+    private request;
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, params?: Record<string, string>): Promise<T>;
+}
+
+/** Response types for the Cogspace TypeScript SDK v0.2.0 */
+/** A knowledge graph edge attached to a search result. */
+interface GraphRelation {
+    path: string;
+    rel_type: "IMPLEMENTS" | "EXTENDS" | "AVOIDS" | "CONFLICTS" | "REFERENCES";
+    topic: string;
+    layer: string;
+}
+interface SearchItem {
+    path: string;
+    content: string;
+    score: number;
+    layer: string;
+    confidence: number;
+    /** Knowledge graph neighbors — empty if graph unavailable or file has no edges. */
+    related: GraphRelation[];
+}
+interface SearchResponse {
+    results: SearchItem[];
+    total: number;
+    query: string;
+    mode: string;
+}
+interface ReadResponse {
+    path: string;
+    content: string;
+    layer: string;
+    size_bytes: number;
+    frontmatter: Record<string, unknown>;
+}
+interface WriteResponse {
+    path: string;
+    status: "created" | "updated";
+    reindex_queued: boolean;
+}
+interface ListResponse {
+    tree: Record<string, unknown>;
+    file_count: number;
+    folder: string;
+}
+interface Space {
+    id: string;
+    user_id: string;
+    name: string;
+    created_at: string;
+}
+interface SearchOptions {
+    limit?: number;
+    layer?: string;
+}
+interface AddOptions {
+    confidence?: number;
+    relates_to?: string[];
+    agent_id?: string;
+}
+
+/** SpaceClient — all operations scoped to a single Cogspace space. */
+
+declare class SpaceClient {
+    private readonly client;
+    readonly spaceId: string;
+    constructor(client: HttpClient, spaceId: string);
+    private path;
+    /**
+     * List all files in a folder.
+     * @param folder - Folder to list (e.g. "expertise"). Empty = entire space.
+     */
+    list(folder?: string): Promise<ListResponse>;
+    /**
+     * Retrieve a single file by path.
+     * @param path - Relative file path (e.g. "expertise/retry.md").
+     */
+    retrieve(path: string): Promise<ReadResponse>;
+    /**
+     * Search all layers (vectors + BM25 + knowledge graph).
+     * @param query - What to search for.
+     * @param options.limit - Max results. Default 10, max 100.
+     * @param options.layer - Optional filter: "expertise", "memory", or "root".
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+    /**
+     * Add or update knowledge. All layers updated automatically.
+     * @param path - Where to write (e.g. "expertise/retry.md").
+     * @param content - Markdown content.
+     * @param layer - "expertise", "memory", or "root".
+     * @param topic - Category/topic for this knowledge.
+     * @param options.confidence - How certain (0.0-1.0). Default 0.9.
+     * @param options.relates_to - Related file names.
+     */
+    add(path: string, content: string, layer: "expertise" | "memory" | "root", topic: string, options?: AddOptions): Promise<WriteResponse>;
+    /**
+     * Delete knowledge from all layers (cascading).
+     * @param path - Relative file path to delete.
+     */
+    forget(path: string): Promise<void>;
+}
+
+/** Cogspace SDK error hierarchy. */
+declare class CogspaceError extends Error {
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    constructor(message: string, status?: number, code?: string);
+}
+declare class AuthError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class NotFoundError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class RateLimitError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class ServerError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class TimeoutError extends CogspaceError {
+    constructor(message: string);
+}
+declare class LimitExceededError extends CogspaceError {
+    constructor(message: string);
+}
+
+/**
+ * Cogspace TypeScript SDK v0.2.0 — persistent knowledge layer for AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { Cogspace } from "@cogspace/sdk";
+ *
+ * // Reads COGSPACE_API_KEY from environment
+ * const cog = new Cogspace();
+ * const space = await cog.space("my-agent");
+ *
+ * // See what exists
+ * const files = await space.list("expertise");
+ *
+ * // Add knowledge
+ * await space.add(
+ *   "expertise/retry.md",
+ *   "# Retry Patterns\nUse exponential backoff...",
+ *   "expertise",
+ *   "retry-patterns",
+ *   { confidence: 0.95 }
+ * );
+ *
+ * // Search
+ * const results = await space.search("retry logic", { limit: 5 });
+ *
+ * // Retrieve a file
+ * const file = await space.retrieve("expertise/retry.md");
+ *
+ * // Delete
+ * await space.forget("expertise/retry.md");
+ * ```
+ */
+
+interface CogspaceConfig extends ClientConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+/**
+ * Cogspace client. Instantiate once per process and reuse.
+ *
+ * Reads COGSPACE_API_KEY from environment automatically.
+ */
+declare class Cogspace {
+    private readonly client;
+    private readonly spaceCache;
+    constructor(config?: CogspaceConfig);
+    private resolveSpaceId;
+    /** Get a space-scoped client by name or ID. */
+    space(nameOrId: string): Promise<SpaceClient>;
+    /** List all your spaces. */
+    listSpaces(): Promise<Space[]>;
+    /** Create a new space. */
+    createSpace(name: string): Promise<Space>;
+}
+
+export { type AddOptions, AuthError, Cogspace, type CogspaceConfig, CogspaceError, HttpClient, LimitExceededError, type ListResponse, NotFoundError, RateLimitError, type ReadResponse, type SearchItem, type SearchOptions, type SearchResponse, ServerError, type Space, SpaceClient, TimeoutError, type WriteResponse };

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+/** HTTP client for the Cogspace TypeScript SDK. Zero dependencies — native fetch. */
+interface ClientConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(config?: ClientConfig);
+    private headers;
+    private request;
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, params?: Record<string, string>): Promise<T>;
+}
+
+/** Response types for the Cogspace TypeScript SDK v0.2.0 */
+/** A knowledge graph edge attached to a search result. */
+interface GraphRelation {
+    path: string;
+    rel_type: "IMPLEMENTS" | "EXTENDS" | "AVOIDS" | "CONFLICTS" | "REFERENCES";
+    topic: string;
+    layer: string;
+}
+interface SearchItem {
+    path: string;
+    content: string;
+    score: number;
+    layer: string;
+    confidence: number;
+    /** Knowledge graph neighbors — empty if graph unavailable or file has no edges. */
+    related: GraphRelation[];
+}
+interface SearchResponse {
+    results: SearchItem[];
+    total: number;
+    query: string;
+    mode: string;
+}
+interface ReadResponse {
+    path: string;
+    content: string;
+    layer: string;
+    size_bytes: number;
+    frontmatter: Record<string, unknown>;
+}
+interface WriteResponse {
+    path: string;
+    status: "created" | "updated";
+    reindex_queued: boolean;
+}
+interface ListResponse {
+    tree: Record<string, unknown>;
+    file_count: number;
+    folder: string;
+}
+interface Space {
+    id: string;
+    user_id: string;
+    name: string;
+    created_at: string;
+}
+interface SearchOptions {
+    limit?: number;
+    layer?: string;
+}
+interface AddOptions {
+    confidence?: number;
+    relates_to?: string[];
+    agent_id?: string;
+}
+
+/** SpaceClient — all operations scoped to a single Cogspace space. */
+
+declare class SpaceClient {
+    private readonly client;
+    readonly spaceId: string;
+    constructor(client: HttpClient, spaceId: string);
+    private path;
+    /**
+     * List all files in a folder.
+     * @param folder - Folder to list (e.g. "expertise"). Empty = entire space.
+     */
+    list(folder?: string): Promise<ListResponse>;
+    /**
+     * Retrieve a single file by path.
+     * @param path - Relative file path (e.g. "expertise/retry.md").
+     */
+    retrieve(path: string): Promise<ReadResponse>;
+    /**
+     * Search all layers (vectors + BM25 + knowledge graph).
+     * @param query - What to search for.
+     * @param options.limit - Max results. Default 10, max 100.
+     * @param options.layer - Optional filter: "expertise", "memory", or "root".
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+    /**
+     * Add or update knowledge. All layers updated automatically.
+     * @param path - Where to write (e.g. "expertise/retry.md").
+     * @param content - Markdown content.
+     * @param layer - "expertise", "memory", or "root".
+     * @param topic - Category/topic for this knowledge.
+     * @param options.confidence - How certain (0.0-1.0). Default 0.9.
+     * @param options.relates_to - Related file names.
+     */
+    add(path: string, content: string, layer: "expertise" | "memory" | "root", topic: string, options?: AddOptions): Promise<WriteResponse>;
+    /**
+     * Delete knowledge from all layers (cascading).
+     * @param path - Relative file path to delete.
+     */
+    forget(path: string): Promise<void>;
+}
+
+/** Cogspace SDK error hierarchy. */
+declare class CogspaceError extends Error {
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    constructor(message: string, status?: number, code?: string);
+}
+declare class AuthError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class NotFoundError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class RateLimitError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class ServerError extends CogspaceError {
+    constructor(message: string, status?: number);
+}
+declare class TimeoutError extends CogspaceError {
+    constructor(message: string);
+}
+declare class LimitExceededError extends CogspaceError {
+    constructor(message: string);
+}
+
+/**
+ * Cogspace TypeScript SDK v0.2.0 — persistent knowledge layer for AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { Cogspace } from "@cogspace/sdk";
+ *
+ * // Reads COGSPACE_API_KEY from environment
+ * const cog = new Cogspace();
+ * const space = await cog.space("my-agent");
+ *
+ * // See what exists
+ * const files = await space.list("expertise");
+ *
+ * // Add knowledge
+ * await space.add(
+ *   "expertise/retry.md",
+ *   "# Retry Patterns\nUse exponential backoff...",
+ *   "expertise",
+ *   "retry-patterns",
+ *   { confidence: 0.95 }
+ * );
+ *
+ * // Search
+ * const results = await space.search("retry logic", { limit: 5 });
+ *
+ * // Retrieve a file
+ * const file = await space.retrieve("expertise/retry.md");
+ *
+ * // Delete
+ * await space.forget("expertise/retry.md");
+ * ```
+ */
+
+interface CogspaceConfig extends ClientConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+/**
+ * Cogspace client. Instantiate once per process and reuse.
+ *
+ * Reads COGSPACE_API_KEY from environment automatically.
+ */
+declare class Cogspace {
+    private readonly client;
+    private readonly spaceCache;
+    constructor(config?: CogspaceConfig);
+    private resolveSpaceId;
+    /** Get a space-scoped client by name or ID. */
+    space(nameOrId: string): Promise<SpaceClient>;
+    /** List all your spaces. */
+    listSpaces(): Promise<Space[]>;
+    /** Create a new space. */
+    createSpace(name: string): Promise<Space>;
+}
+
+export { type AddOptions, AuthError, Cogspace, type CogspaceConfig, CogspaceError, HttpClient, LimitExceededError, type ListResponse, NotFoundError, RateLimitError, type ReadResponse, type SearchItem, type SearchOptions, type SearchResponse, ServerError, type Space, SpaceClient, TimeoutError, type WriteResponse };

package/dist/index.js

@@ -0,0 +1,265 @@
+// src/errors.ts
+var CogspaceError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "CogspaceError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var AuthError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "AuthError";
+  }
+};
+var NotFoundError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends CogspaceError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "ServerError";
+  }
+};
+var TimeoutError = class extends CogspaceError {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var LimitExceededError = class extends CogspaceError {
+  constructor(message) {
+    super(message);
+    this.name = "LimitExceededError";
+  }
+};
+function raiseForStatus(status, body) {
+  const message = String(body.detail ?? body.message ?? `HTTP ${status}`);
+  const code = body.error;
+  if (status === 401) throw new AuthError(message, status);
+  if (status === 404) throw new NotFoundError(message, status);
+  if (status === 429) throw new RateLimitError(message, status);
+  if (status >= 500) throw new ServerError(message, status);
+  throw new CogspaceError(message, status, code);
+}
+
+// src/client.ts
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var HttpClient = class {
+  constructor(config = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env["COGSPACE_API_KEY"] : void 0;
+    const key = config.apiKey ?? envKey ?? "";
+    if (!key) {
+      throw new Error(
+        "API key is required. Pass apiKey: in config or set the COGSPACE_API_KEY environment variable."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (config.baseUrl ?? "https://platform.cogspace.ai").replace(/\/$/, "");
+    this.timeout = config.timeout ?? 3e4;
+    this.maxRetries = config.maxRetries ?? 3;
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": "cogspace-ts/0.2.0"
+    };
+  }
+  async request(method, path, body, params) {
+    let url = `${this.baseUrl}${path}`;
+    if (params && Object.keys(params).length > 0) {
+      url += "?" + new URLSearchParams(params).toString();
+    }
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      let response;
+      try {
+        response = await fetch(url, {
+          method,
+          headers: this.headers(),
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof Error && err.name === "AbortError") {
+          throw new TimeoutError(`Request timed out: ${path}`);
+        }
+        throw err;
+      }
+      clearTimeout(timer);
+      if (!RETRY_STATUSES.has(response.status)) {
+        if (response.status >= 400) {
+          let errBody = {};
+          try {
+            errBody = await response.json();
+          } catch {
+          }
+          raiseForStatus(response.status, errBody);
+        }
+        if (response.status === 204 || response.headers.get("content-length") === "0") {
+          return void 0;
+        }
+        return response.json();
+      }
+      if (attempt < this.maxRetries - 1) {
+        let wait = Math.pow(2, attempt) * 1e3;
+        const retryAfter = response.headers.get("Retry-After");
+        if (retryAfter) wait = parseFloat(retryAfter) * 1e3;
+        await new Promise((r) => setTimeout(r, wait));
+        let errBody = {};
+        try {
+          errBody = await response.json();
+        } catch {
+        }
+        lastError = new RateLimitError(String(errBody.detail ?? `HTTP ${response.status}`), response.status);
+      } else {
+        let errBody = {};
+        try {
+          errBody = await response.json();
+        } catch {
+        }
+        raiseForStatus(response.status, errBody);
+      }
+    }
+    throw lastError ?? new RateLimitError("Max retries exceeded");
+  }
+  get(path, params) {
+    return this.request("GET", path, void 0, params);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  delete(path, params) {
+    return this.request("DELETE", path, void 0, params);
+  }
+};
+
+// src/space.ts
+var MAX_LIMIT = 100;
+var SpaceClient = class {
+  constructor(client, spaceId) {
+    this.client = client;
+    this.spaceId = spaceId;
+  }
+  path(endpoint) {
+    return `/spaces/${this.spaceId}/${endpoint}`;
+  }
+  /**
+   * List all files in a folder.
+   * @param folder - Folder to list (e.g. "expertise"). Empty = entire space.
+   */
+  list(folder = "") {
+    return this.client.get(this.path("list"), { folder });
+  }
+  /**
+   * Retrieve a single file by path.
+   * @param path - Relative file path (e.g. "expertise/retry.md").
+   */
+  retrieve(path) {
+    return this.client.get(this.path("retrieve"), { path });
+  }
+  /**
+   * Search all layers (vectors + BM25 + knowledge graph).
+   * @param query - What to search for.
+   * @param options.limit - Max results. Default 10, max 100.
+   * @param options.layer - Optional filter: "expertise", "memory", or "root".
+   */
+  async search(query, options = {}) {
+    const limit = options.limit ?? 10;
+    if (limit > MAX_LIMIT) {
+      throw new LimitExceededError(`limit must be <= ${MAX_LIMIT}. Got: ${limit}`);
+    }
+    return this.client.post(this.path("search"), {
+      query,
+      limit,
+      layer: options.layer ?? null
+    });
+  }
+  /**
+   * Add or update knowledge. All layers updated automatically.
+   * @param path - Where to write (e.g. "expertise/retry.md").
+   * @param content - Markdown content.
+   * @param layer - "expertise", "memory", or "root".
+   * @param topic - Category/topic for this knowledge.
+   * @param options.confidence - How certain (0.0-1.0). Default 0.9.
+   * @param options.relates_to - Related file names.
+   */
+  add(path, content, layer, topic, options = {}) {
+    return this.client.post(this.path("add"), {
+      path,
+      content,
+      layer,
+      topic,
+      confidence: options.confidence ?? 0.9,
+      relates_to: options.relates_to ?? null,
+      agent_id: options.agent_id ?? "default"
+    });
+  }
+  /**
+   * Delete knowledge from all layers (cascading).
+   * @param path - Relative file path to delete.
+   */
+  forget(path) {
+    return this.client.delete(this.path("forget"), { path });
+  }
+};
+
+// src/index.ts
+var Cogspace = class {
+  constructor(config = {}) {
+    this.spaceCache = /* @__PURE__ */ new Map();
+    this.client = new HttpClient(config);
+  }
+  async resolveSpaceId(nameOrId) {
+    const cached = this.spaceCache.get(nameOrId);
+    if (cached) return cached;
+    const spaces = await this.client.get("/spaces");
+    for (const s of spaces) {
+      this.spaceCache.set(s.name, s.id);
+      this.spaceCache.set(s.id, s.id);
+      if (s.name === nameOrId || s.id === nameOrId) {
+        return s.id;
+      }
+    }
+    throw new NotFoundError(`Space not found: ${nameOrId}`);
+  }
+  /** Get a space-scoped client by name or ID. */
+  async space(nameOrId) {
+    const spaceId = await this.resolveSpaceId(nameOrId);
+    return new SpaceClient(this.client, spaceId);
+  }
+  /** List all your spaces. */
+  listSpaces() {
+    return this.client.get("/spaces");
+  }
+  /** Create a new space. */
+  createSpace(name) {
+    return this.client.post("/spaces", { name });
+  }
+};
+export {
+  AuthError,
+  Cogspace,
+  CogspaceError,
+  HttpClient,
+  LimitExceededError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  SpaceClient,
+  TimeoutError
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "cogspace",
+  "version": "0.3.1",
+  "description": "Official Cogspace SDK — add a knowledge layer to any AI agent",
+  "keywords": [
+    "ai",
+    "agents",
+    "knowledge",
+    "memory",
+    "rag",
+    "sdk",
+    "cogspace"
+  ],
+  "homepage": "https://cogspace.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jack-Pision/cogspace-ai.git",
+    "directory": "sdk/typescript"
+  },
+  "license": "MIT",
+  "author": "Cogspace",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}