@proteos/sdk 0.18.1

package/src/iterator.ts

@@ -0,0 +1,183 @@
+import type { ListOptions, ListResult } from './types/common.js'
+
+/**
+ * Sentinel symbol indicating iteration is complete.
+ */
+export const DONE = Symbol('DONE')
+export type Done = typeof DONE
+
+/**
+ * Function type for fetching a page of results.
+ * @typeParam T - The type of items in the list
+ * @typeParam O - The type of options for the list request
+ */
+export type ListFn<T, O extends ListOptions> = (options: O) => Promise<ListResult<T>>
+
+/**
+ * Default page size for pagination.
+ */
+export const DEFAULT_PAGE_SIZE = 100
+
+/**
+ * Async iterator for paginated resources.
+ * Provides Google Cloud-style iteration with automatic page fetching.
+ *
+ * @typeParam T - The type of items being iterated
+ * @typeParam O - The type of options for list requests
+ *
+ * @example
+ * ```ts
+ * // Using for-await-of
+ * const iterator = new PageIterator(fetchEntities, { page_size: 50 });
+ * for await (const entity of iterator) {
+ *   console.log(entity);
+ * }
+ *
+ * // Using next() directly
+ * const item = await iterator.next();
+ * if (item !== DONE) {
+ *   console.log(item);
+ * }
+ *
+ * // Collecting all items
+ * const allItems = await iterator.all();
+ * ```
+ */
+export class PageIterator<T, O extends ListOptions> implements AsyncIterable<T> {
+  private readonly listFn: ListFn<T, O>
+  private readonly options: O
+  // Pages are 0-indexed across all Proteos services. First fetch is page 0,
+  // last is pagesTotal - 1.
+  private page: number = 0
+  private buffer: T[] = []
+  private bufferIndex: number = 0
+  private pagesTotal: number | undefined
+
+  /**
+   * Creates a new PageIterator.
+   *
+   * @param listFn - Function to fetch a page of results
+   * @param options - Options for list requests (including pagination)
+   */
+  constructor(listFn: ListFn<T, O>, options: O) {
+    this.listFn = listFn
+    this.options = { ...options }
+
+    // Set default page size if not provided
+    if (!this.options.page_size) {
+      this.options.page_size = DEFAULT_PAGE_SIZE
+    }
+  }
+
+  /**
+   * Returns the next item in the iterator.
+   * Returns DONE symbol when iteration is complete.
+   *
+   * @returns The next item or DONE
+   *
+   * @example
+   * ```ts
+   * const item = await iterator.next();
+   * if (item !== DONE) {
+   *   console.log(item);
+   * }
+   * ```
+   */
+  async next(): Promise<T | Done> {
+    // Return next item from buffer if available
+    if (this.bufferIndex < this.buffer.length) {
+      const item = this.buffer[this.bufferIndex]
+      this.bufferIndex++
+      return item as T
+    }
+
+    // Check if we've exhausted all pages. Pages are 0-indexed, so the last
+    // valid page is `pagesTotal - 1`; once `this.page` reaches `pagesTotal`
+    // there are no more to fetch.
+    if (this.pagesTotal !== undefined && this.page >= this.pagesTotal) {
+      return DONE
+    }
+
+    // Fetch next page
+    const result = await this.listFn({
+      ...this.options,
+      page: this.page,
+    })
+
+    // Update total pages from response
+    this.pagesTotal = result.meta.pages_total
+
+    // Empty page means we're done
+    if (result.data.length === 0) {
+      return DONE
+    }
+
+    // Update buffer and indices
+    this.buffer = result.data
+    this.bufferIndex = 1 // Start at 1 since we'll return index 0
+    this.page++
+
+    return this.buffer[0] as T
+  }
+
+  /**
+   * Collects all remaining items into an array.
+   * Useful when you need all items at once.
+   *
+   * @returns Array of all remaining items
+   *
+   * @example
+   * ```ts
+   * const allEntities = await iterator.all();
+   * console.log(`Found ${allEntities.length} entities`);
+   * ```
+   */
+  async all(): Promise<T[]> {
+    const items: T[] = []
+
+    while (true) {
+      const item = await this.next()
+      if (item === DONE) {
+        break
+      }
+      items.push(item)
+    }
+
+    return items
+  }
+
+  /**
+   * Implements AsyncIterable for use with for-await-of loops.
+   *
+   * @example
+   * ```ts
+   * for await (const entity of iterator) {
+   *   console.log(entity.name);
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (true) {
+      const item = await this.next()
+      if (item === DONE) {
+        return
+      }
+      yield item
+    }
+  }
+}
+
+/**
+ * Creates a PageIterator with the given list function and options.
+ * Convenience function for creating iterators.
+ *
+ * @param listFn - Function to fetch a page of results
+ * @param options - Options for list requests
+ * @returns A new PageIterator instance
+ */
+export function createIterator<T, O extends ListOptions>(
+  listFn: ListFn<T, O>,
+  options: O,
+): PageIterator<T, O> {
+  return new PageIterator(listFn, options)
+}

package/src/knowledge/graph.ts

@@ -0,0 +1,35 @@
+import type { ProteosClient } from '../client.js'
+import type { GetGraphOptions, KnowledgeGraph } from './types.js'
+
+const GRAPH_BASE_PATH = '/knowledge/v1/graph'
+
+/**
+ * Service for the whole-org knowledge graph (bulk read backing the radiant graph
+ * view). One request returns lean nodes (with per-node label ids + degree),
+ * links, the org label set and the total node count.
+ */
+export interface GraphService {
+  /**
+   * Reads the whole org graph in one payload. `options.label_ids` prunes to
+   * nodes carrying ANY of the given labels (union); omitted returns everything.
+   */
+  get(options?: GetGraphOptions): Promise<KnowledgeGraph>
+}
+
+/**
+ * Implementation of GraphService.
+ */
+export class GraphServiceImpl implements GraphService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async get(options: GetGraphOptions = {}): Promise<KnowledgeGraph> {
+    // The server reads label_ids as a single comma-separated query param (the
+    // query binder takes only the first value of a repeated param), so the
+    // union list is joined here rather than appended as repeated params.
+    const query: { label_ids?: string } = {}
+    if (options.label_ids && options.label_ids.length > 0) {
+      query.label_ids = options.label_ids.join(',')
+    }
+    return this.client.requestWithQuery<KnowledgeGraph>('GET', GRAPH_BASE_PATH, query)
+  }
+}

package/src/knowledge/index.ts

@@ -0,0 +1,104 @@
+import type { ProteosClient } from '../client.js'
+import { type GraphService, GraphServiceImpl } from './graph.js'
+import { type LabelService, LabelServiceImpl } from './labels.js'
+import { type LinkService, LinkServiceImpl } from './links.js'
+import { type NodeService, NodeServiceImpl } from './nodes.js'
+import { type RecordLinkService, RecordLinkServiceImpl } from './record-links.js'
+
+/**
+ * Facade for the knowledge-service (graph-native knowledge base: nodes, typed
+ * links, labels, content sub-resource, keyword search and neighbor traversal).
+ *
+ * Usage:
+ * ```ts
+ * const client = new ProteosClient({ baseUrl, tokenProvider });
+ * const knowledge = new KnowledgeClient(client);
+ * const node = await knowledge.nodes.create({ title: 'ADR 1', type: 'markdown', status: 'draft', content: '# ...' });
+ * const hits = await knowledge.nodes.search({ query: 'invoicing' });
+ * ```
+ */
+export class KnowledgeClient {
+  readonly nodes: NodeService
+  readonly links: LinkService
+  /** Node→record edges (links to data-service records): `knowledge.recordLinks`. */
+  readonly recordLinks: RecordLinkService
+  readonly labels: LabelService
+  /** Whole-org graph bulk read (radiant graph view): `knowledge.graph.get()`. */
+  readonly graph: GraphService
+
+  constructor(client: ProteosClient) {
+    this.nodes = new NodeServiceImpl(client)
+    this.links = new LinkServiceImpl(client)
+    this.recordLinks = new RecordLinkServiceImpl(client)
+    this.labels = new LabelServiceImpl(client)
+    this.graph = new GraphServiceImpl(client)
+  }
+}
+
+// Re-export service interfaces
+export type { GraphService } from './graph.js'
+export type { LabelService } from './labels.js'
+export type { LinkService } from './links.js'
+export type { NodeService } from './nodes.js'
+export type { RecordLinkService } from './record-links.js'
+
+// Re-export types
+export type {
+  ContentMatch,
+  ContentResponse,
+  CreateLabelRequest,
+  CreateLinkRequest,
+  CreateNodeRequest,
+  CreateRecordLinkRequest,
+  EditContentRequest,
+  EditContentResponse,
+  GetGraphOptions,
+  InlineLinkRequest,
+  KnowledgeGraph,
+  KnowledgeGraphLink,
+  KnowledgeGraphNode,
+  KnowledgeLabel,
+  KnowledgeLink,
+  KnowledgeNode,
+  KnowledgeNodeLabel,
+  KnowledgeNodeMetadata,
+  KnowledgeNodeSearchResult,
+  KnowledgeRecordLink,
+  LinkType,
+  ListLabelsOptions,
+  ListLinksOptions,
+  ListNodesOptions,
+  ListRecordLinksOptions,
+  MatchMode,
+  NeighborDirection,
+  NeighborEdge,
+  NeighborNode,
+  NeighborsOptions,
+  NodeContentMatches,
+  NodeNeighborhood,
+  NodeOutline,
+  NodeStatus,
+  NodeType,
+  OutlineHeading,
+  OutlineRequest,
+  OutlineResponse,
+  SearchContentRequest,
+  SearchContentResponse,
+  SearchNodesRequest,
+  UpdateLabelRequest,
+  UpdateLinkRequest,
+  UpdateNodeRequest,
+  WriteContentResponse,
+} from './types.js'
+
+// Re-export Zod schemas
+export {
+  KnowledgeLabelSchema,
+  KnowledgeLinkSchema,
+  KnowledgeNodeLabelSchema,
+  KnowledgeNodeMetadataSchema,
+  KnowledgeNodeSchema,
+  KnowledgeNodeSearchResultSchema,
+  KnowledgeRecordLinkSchema,
+  NodeNeighborhoodSchema,
+} from './types.js'

package/src/knowledge/labels.ts

@@ -0,0 +1,70 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateLabelRequest,
+  KnowledgeLabel,
+  ListLabelsOptions,
+  UpdateLabelRequest,
+} from './types.js'
+
+const LABELS_BASE_PATH = '/knowledge/v1/labels'
+
+/**
+ * Service for knowledge labels (categorization handles). To attach/detach a
+ * label to a node, use the node service's label methods.
+ */
+export interface LabelService {
+  /** Lists labels as an async iterator (pages are 0-indexed). */
+  list(options?: ListLabelsOptions): PageIterator<KnowledgeLabel, ListLabelsOptions>
+
+  /** Fetches a single page of labels. */
+  listPage(options?: ListLabelsOptions): Promise<ListResult<KnowledgeLabel>>
+
+  /** Gets a single label by id. */
+  get(id: string): Promise<KnowledgeLabel>
+
+  /** Creates a label. */
+  create(request: CreateLabelRequest): Promise<KnowledgeLabel>
+
+  /** Updates a label. */
+  update(id: string, request: UpdateLabelRequest): Promise<KnowledgeLabel>
+
+  /** Deletes a label; its node associations cascade. */
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Implementation of LabelService.
+ */
+export class LabelServiceImpl implements LabelService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListLabelsOptions = {}): PageIterator<KnowledgeLabel, ListLabelsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListLabelsOptions = {}): Promise<ListResult<KnowledgeLabel>> {
+    return this.client.requestWithQuery<ListResult<KnowledgeLabel>>(
+      'GET',
+      LABELS_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(id: string): Promise<KnowledgeLabel> {
+    return this.client.request<KnowledgeLabel>('GET', `${LABELS_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateLabelRequest): Promise<KnowledgeLabel> {
+    return this.client.request<KnowledgeLabel>('POST', LABELS_BASE_PATH, request)
+  }
+
+  async update(id: string, request: UpdateLabelRequest): Promise<KnowledgeLabel> {
+    return this.client.request<KnowledgeLabel>('PATCH', `${LABELS_BASE_PATH}/${id}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${LABELS_BASE_PATH}/${id}`)
+  }
+}

package/src/knowledge/links.ts

@@ -0,0 +1,65 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateLinkRequest,
+  KnowledgeLink,
+  ListLinksOptions,
+  UpdateLinkRequest,
+} from './types.js'
+
+const LINKS_BASE_PATH = '/knowledge/v1/links'
+
+/**
+ * Service for typed edges (links) between knowledge nodes.
+ */
+export interface LinkService {
+  /** Lists links as an async iterator (pages are 0-indexed). */
+  list(options?: ListLinksOptions): PageIterator<KnowledgeLink, ListLinksOptions>
+
+  /** Fetches a single page of links. */
+  listPage(options?: ListLinksOptions): Promise<ListResult<KnowledgeLink>>
+
+  /** Gets a single link by id. */
+  get(id: string): Promise<KnowledgeLink>
+
+  /** Creates a typed edge between two nodes. */
+  create(request: CreateLinkRequest): Promise<KnowledgeLink>
+
+  /** Updates a link's type / description. */
+  update(id: string, request: UpdateLinkRequest): Promise<KnowledgeLink>
+
+  /** Deletes a link. */
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Implementation of LinkService.
+ */
+export class LinkServiceImpl implements LinkService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListLinksOptions = {}): PageIterator<KnowledgeLink, ListLinksOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListLinksOptions = {}): Promise<ListResult<KnowledgeLink>> {
+    return this.client.requestWithQuery<ListResult<KnowledgeLink>>('GET', LINKS_BASE_PATH, options)
+  }
+
+  async get(id: string): Promise<KnowledgeLink> {
+    return this.client.request<KnowledgeLink>('GET', `${LINKS_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateLinkRequest): Promise<KnowledgeLink> {
+    return this.client.request<KnowledgeLink>('POST', LINKS_BASE_PATH, request)
+  }
+
+  async update(id: string, request: UpdateLinkRequest): Promise<KnowledgeLink> {
+    return this.client.request<KnowledgeLink>('PATCH', `${LINKS_BASE_PATH}/${id}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${LINKS_BASE_PATH}/${id}`)
+  }
+}

package/src/knowledge/nodes.ts

@@ -0,0 +1,198 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  ContentResponse,
+  CreateNodeRequest,
+  EditContentRequest,
+  EditContentResponse,
+  KnowledgeLabel,
+  KnowledgeNode,
+  KnowledgeNodeLabel,
+  KnowledgeNodeMetadata,
+  KnowledgeNodeSearchResult,
+  ListNodesOptions,
+  NeighborsOptions,
+  NodeNeighborhood,
+  OutlineRequest,
+  OutlineResponse,
+  SearchContentRequest,
+  SearchContentResponse,
+  SearchNodesRequest,
+  UpdateNodeRequest,
+  WriteContentResponse,
+} from './types.js'
+
+const NODES_BASE_PATH = '/knowledge/v1/nodes'
+
+/**
+ * Service for knowledge nodes and their content, search, graph neighbors and
+ * labels. Reads return node metadata (no body) by default; the body is fetched
+ * explicitly with {@link NodeService.getContent}.
+ */
+export interface NodeService {
+  /** Lists node metadata as an async iterator (pages are 0-indexed). */
+  list(options?: ListNodesOptions): PageIterator<KnowledgeNodeMetadata, ListNodesOptions>
+
+  /** Fetches a single page of node metadata. */
+  listPage(options?: ListNodesOptions): Promise<ListResult<KnowledgeNodeMetadata>>
+
+  /** Gets a node's metadata (body excluded). */
+  get(id: string): Promise<KnowledgeNodeMetadata>
+
+  /** Creates a node, optionally connecting it to labels/links in one call. */
+  create(request: CreateNodeRequest): Promise<KnowledgeNode>
+
+  /** Updates a node's metadata (title / status / summary). */
+  update(id: string, request: UpdateNodeRequest): Promise<KnowledgeNodeMetadata>
+
+  /** Hard-deletes a node; its links and label associations cascade. */
+  delete(id: string): Promise<void>
+
+  /**
+   * Hybrid retrieval. Only `keyword` is wired today; `semantic`/`hybrid` throw a
+   * 501 ProteosError until embeddings land.
+   */
+  search(request: SearchNodesRequest): Promise<ListResult<KnowledgeNodeSearchResult>>
+
+  /** Depth-bounded graph walk from a node. */
+  neighbors(id: string, options?: NeighborsOptions): Promise<NodeNeighborhood>
+
+  /** Reads a node's raw content body plus its line count. */
+  getContent(id: string): Promise<ContentResponse>
+
+  /** Overwrites a node's content body. Rejects derived (file/url) nodes. */
+  writeContent(id: string, content: string): Promise<WriteContentResponse>
+
+  /** Applies a surgical anchored edit to a node's content body. */
+  editContent(id: string, request: EditContentRequest): Promise<EditContentResponse>
+
+  /**
+   * Maps each requested node's body by its markdown heading structure (one or
+   * several nodes) — skim a large node, then read just a section's line range.
+   */
+  getOutline(request: OutlineRequest): Promise<OutlineResponse>
+
+  /** Greps each requested node's body for a pattern, with matching lines + context. */
+  searchContent(request: SearchContentRequest): Promise<SearchContentResponse>
+
+  /** Lists the labels attached to a node. */
+  listLabels(id: string): Promise<KnowledgeLabel[]>
+
+  /** Attaches an existing label to a node. */
+  attachLabel(id: string, labelId: string): Promise<KnowledgeNodeLabel>
+
+  /** Detaches a label from a node. */
+  detachLabel(id: string, labelId: string): Promise<void>
+}
+
+/**
+ * Implementation of NodeService.
+ */
+export class NodeServiceImpl implements NodeService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListNodesOptions = {}): PageIterator<KnowledgeNodeMetadata, ListNodesOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListNodesOptions = {}): Promise<ListResult<KnowledgeNodeMetadata>> {
+    // The server reads label_ids as a single comma-separated query param (the query
+    // binder takes only the first value of a repeated param), so the union list is
+    // joined here rather than appended as repeated params (mirrors GraphService.get).
+    const { label_ids, ...rest } = options
+    const query: Record<string, unknown> = { ...rest }
+    if (label_ids && label_ids.length > 0) {
+      query.label_ids = label_ids.join(',')
+    }
+    return this.client.requestWithQuery<ListResult<KnowledgeNodeMetadata>>(
+      'GET',
+      NODES_BASE_PATH,
+      query,
+    )
+  }
+
+  async get(id: string): Promise<KnowledgeNodeMetadata> {
+    return this.client.request<KnowledgeNodeMetadata>('GET', `${NODES_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateNodeRequest): Promise<KnowledgeNode> {
+    return this.client.request<KnowledgeNode>('POST', NODES_BASE_PATH, request)
+  }
+
+  async update(id: string, request: UpdateNodeRequest): Promise<KnowledgeNodeMetadata> {
+    return this.client.request<KnowledgeNodeMetadata>('PATCH', `${NODES_BASE_PATH}/${id}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${NODES_BASE_PATH}/${id}`)
+  }
+
+  async search(request: SearchNodesRequest): Promise<ListResult<KnowledgeNodeSearchResult>> {
+    return this.client.request<ListResult<KnowledgeNodeSearchResult>>(
+      'POST',
+      `${NODES_BASE_PATH}/actions/search`,
+      request,
+    )
+  }
+
+  async neighbors(id: string, options: NeighborsOptions = {}): Promise<NodeNeighborhood> {
+    return this.client.requestWithQuery<NodeNeighborhood>(
+      'GET',
+      `${NODES_BASE_PATH}/${id}/neighbors`,
+      options,
+    )
+  }
+
+  async getContent(id: string): Promise<ContentResponse> {
+    return this.client.request<ContentResponse>('GET', `${NODES_BASE_PATH}/${id}/content`)
+  }
+
+  async writeContent(id: string, content: string): Promise<WriteContentResponse> {
+    return this.client.request<WriteContentResponse>('PUT', `${NODES_BASE_PATH}/${id}/content`, {
+      content,
+    })
+  }
+
+  async editContent(id: string, request: EditContentRequest): Promise<EditContentResponse> {
+    return this.client.request<EditContentResponse>(
+      'POST',
+      `${NODES_BASE_PATH}/${id}/content/actions/edit`,
+      request,
+    )
+  }
+
+  async getOutline(request: OutlineRequest): Promise<OutlineResponse> {
+    return this.client.request<OutlineResponse>(
+      'POST',
+      `${NODES_BASE_PATH}/content/actions/outline`,
+      request,
+    )
+  }
+
+  async searchContent(request: SearchContentRequest): Promise<SearchContentResponse> {
+    return this.client.request<SearchContentResponse>(
+      'POST',
+      `${NODES_BASE_PATH}/content/actions/search`,
+      request,
+    )
+  }
+
+  async listLabels(id: string): Promise<KnowledgeLabel[]> {
+    const result = await this.client.request<{ data: KnowledgeLabel[] }>(
+      'GET',
+      `${NODES_BASE_PATH}/${id}/labels`,
+    )
+    return result.data
+  }
+
+  async attachLabel(id: string, labelId: string): Promise<KnowledgeNodeLabel> {
+    return this.client.request<KnowledgeNodeLabel>('POST', `${NODES_BASE_PATH}/${id}/labels`, {
+      label_id: labelId,
+    })
+  }
+
+  async detachLabel(id: string, labelId: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${NODES_BASE_PATH}/${id}/labels/${labelId}`)
+  }
+}