Foundry SDK

TypeScript/JavaScript client for the Foundry REST API — project memory and security scanning.

Installation

npm install @withfoundry/sdk
# or
pnpm add @withfoundry/sdk

Quick start

import { Foundry } from "@withfoundry/sdk";

const foundry = new Foundry({ apiKey: "key_..." });

// Write a decision to project memory
const { memoryId, status } = await foundry.memory.write({
  projectId: "prj_...",
  type: "decision",
  content: "We use server components for all data fetching.",
});
console.log(`Saved: ${memoryId} (${status})`);

// Get assembled context before generating code
const context = await foundry.memory.context(
  "prj_...",
  "Adding a new API route for user preferences"
);
console.log(context);

// Start a repo scan
const scan = await foundry.scanner.scanRepo({
  projectId: "prj_...",
  repoUrl: "https://github.com/org/repo",
});
console.log(`Scan ${scan.scanId} queued, ~${scan.estimatedDuration}s`);

API

Foundry client

const foundry = new Foundry({ apiKey: "key_...", baseUrl?: "https://api.withfoundry.ai" });

• apiKey (required): Foundry API key.
• baseUrl (optional): API base URL. Defaults to https://api.withfoundry.ai or process.env.FOUNDRY_API_URL.

Memory

• write(input: WriteMemoryRequest) → Promise<{ memoryId: string; status: "queued" }>
  Writes a memory item. Returns immediately; item is indexed asynchronously.

• read(id: string, projectId: string) → Promise<MemoryItem>
  Reads a memory item by ID.

• search(input: SearchMemoryRequest) → Promise<{ items: MemoryItem[]; totalFound: number }>
  Semantic search over project memory.

• list(projectId: string, filters?: ListMemoryFilters) → Promise<{ items: MemoryItem[]; nextCursor: string | null; hasMore: boolean }>
  Paginated list with optional type/status/cursor/limit.

• delete(id: string, projectId: string) → Promise<void>
  Deletes a memory item.

• context(projectId: string, task: string, limit?: number) → Promise<string>
  Returns assembled context for a task (for injection before code generation).

Scanner

• scanRepo(input: ScanRepoInput) → Promise<{ scanId: string; status: string; estimatedDuration: number }>
  Starts an async repo scan. Returns 202-style with scan ID and estimated duration.

• scanFile(input: ScanFileInput) → Promise<{ findings: SecurityFinding[] }>
  Sync single-file scan.

• getScan(scanId: string, projectId: string) → Promise<ScanJobWithFindings>
  Fetches scan job and findings (when completed).

• listScans(projectId: string, cursor?: string, limit?: number) → Promise<{ items: ScanJob[]; nextCursor: string | null; hasMore: boolean }>
  Paginated list of scans.

Types

Exported from @withfoundry/sdk:

• MemoryItem — memory item shape (id, projectId, type, content, metadata, status, accessCount, createdAt, updatedAt).
• ScanJob — scan job (id, projectId, repoUrl, branch, status, filesScanned, findingsTotal, startedAt, completedAt, errorMessage, createdAt).
• SecurityFinding — finding (id, scanJobId, projectId, filePath, lineStart, lineEnd, category, severity, title, description, fixSuggestion, memoryItemId, createdAt).
• FoundrySDKError — error with code, message, statusCode.

Error handling

On API or network errors the SDK throws FoundrySDKError:

import { Foundry, FoundrySDKError } from "@withfoundry/sdk";

try {
  await foundry.memory.read("mem_xxx", "prj_xxx");
} catch (err) {
  if (err instanceof FoundrySDKError) {
    console.log(err.code);       // e.g. "MEMORY_NOT_FOUND"
    console.log(err.statusCode); // e.g. 404
    console.log(err.message);
  }
}

• API errors: code and statusCode match the API response (e.g. MEMORY_NOT_FOUND, 404).
• Network errors: code is NETWORK_ERROR, statusCode is 0.