@proteos/sdk 0.18.1

package/src/knowledge/record-links.ts

@@ -0,0 +1,66 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateRecordLinkRequest,
+  KnowledgeRecordLink,
+  ListRecordLinksOptions,
+} from './types.js'
+
+const RECORD_LINKS_BASE_PATH = '/knowledge/v1/record-links'
+
+/**
+ * Service for node→record edges: links from a knowledge node to a business
+ * record (data-service, identified by `entity_slug` + `record_id`). Immutable —
+ * create / delete only, no update. Filter by `node_id` (a node's records) or by
+ * `entity_slug` + `record_id` (a record's nodes).
+ */
+export interface RecordLinkService {
+  /** Lists record links as an async iterator (pages are 0-indexed). */
+  list(options?: ListRecordLinksOptions): PageIterator<KnowledgeRecordLink, ListRecordLinksOptions>
+
+  /** Fetches a single page of record links. */
+  listPage(options?: ListRecordLinksOptions): Promise<ListResult<KnowledgeRecordLink>>
+
+  /** Gets a single record link by id. */
+  get(id: string): Promise<KnowledgeRecordLink>
+
+  /** Links a node to a business record. */
+  create(request: CreateRecordLinkRequest): Promise<KnowledgeRecordLink>
+
+  /** Removes a record link. */
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Implementation of RecordLinkService.
+ */
+export class RecordLinkServiceImpl implements RecordLinkService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    options: ListRecordLinksOptions = {},
+  ): PageIterator<KnowledgeRecordLink, ListRecordLinksOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListRecordLinksOptions = {}): Promise<ListResult<KnowledgeRecordLink>> {
+    return this.client.requestWithQuery<ListResult<KnowledgeRecordLink>>(
+      'GET',
+      RECORD_LINKS_BASE_PATH,
+      options,
+    )
+  }
+
+  async get(id: string): Promise<KnowledgeRecordLink> {
+    return this.client.request<KnowledgeRecordLink>('GET', `${RECORD_LINKS_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateRecordLinkRequest): Promise<KnowledgeRecordLink> {
+    return this.client.request<KnowledgeRecordLink>('POST', RECORD_LINKS_BASE_PATH, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${RECORD_LINKS_BASE_PATH}/${id}`)
+  }
+}

package/src/knowledge/types.ts

@@ -0,0 +1,569 @@
+import { z } from 'zod'
+import {
+  type AuditFields,
+  AuditFieldsSchema,
+  type ListOptions,
+  type UserRef,
+  UserRefSchema,
+} from '../types/common.js'
+
+// ============================================================================
+// Enums
+// ============================================================================
+
+/** A node's kind. `markdown` is authored; `file`/`url` bodies are derived. */
+export type NodeType = 'markdown' | 'file' | 'url'
+
+/** Lifecycle state of a node. */
+export type NodeStatus = 'draft' | 'published' | 'archived'
+
+/** Typed edge kinds in the knowledge graph. */
+export type LinkType =
+  | 'references'
+  | 'relates_to'
+  | 'depends_on'
+  | 'part_of'
+  | 'derived_from'
+  | 'contradicts'
+  | 'supports'
+  | 'duplicates'
+  | 'superseded_by'
+
+/**
+ * Retrieval mode for `nodes.search`. Only `keyword` is wired today; `semantic`
+ * and `hybrid` are reserved (the server returns 501 until embeddings land).
+ */
+export type MatchMode = 'hybrid' | 'semantic' | 'keyword'
+
+/** Traversal direction for `nodes.neighbors`. */
+export type NeighborDirection = 'out' | 'in' | 'both'
+
+// ============================================================================
+// Entity Types
+// ============================================================================
+
+/**
+ * A node's metadata — everything except the (potentially huge) `content` body
+ * and the derived embedding vector. This is what list / get / search / neighbors
+ * return by default.
+ */
+export interface KnowledgeNodeMetadata extends AuditFields {
+  id: string
+  org_id: string
+  title: string
+  type: NodeType
+  status: NodeStatus
+  /** Embedding provenance (null until ingestion runs). */
+  embedding_model?: string | null
+  embedded_at?: string | null
+  /** Source pointer for `file` nodes (storage-service file id). */
+  file_id?: string | null
+  /** Source pointer for `url` nodes. */
+  url?: string | null
+  summary?: string | null
+  /**
+   * Temporal validity window (RFC3339), decoupled from `created_at`. `valid_from`
+   * is when the asserted fact starts being true, `valid_until` when it stops.
+   * Either null = unbounded on that side (both null = always valid). Half-open
+   * `[valid_from, valid_until)`.
+   */
+  valid_from?: string | null
+  valid_until?: string | null
+}
+
+/** A full node: its metadata plus the markdown `content` body. */
+export interface KnowledgeNode extends KnowledgeNodeMetadata {
+  content: string
+}
+
+/** A node returned by search, with its relevance `score`. */
+export interface KnowledgeNodeSearchResult extends KnowledgeNodeMetadata {
+  score: number
+}
+
+/** A typed, directed edge between two nodes. */
+export interface KnowledgeLink extends AuditFields {
+  id: string
+  org_id: string
+  from_id: string
+  to_id: string
+  type: LinkType
+  description?: string | null
+}
+
+/**
+ * A directed edge from a knowledge node to a business record (data-service,
+ * identified by `entity_slug` + `record_id`). Immutable once created — only
+ * `created_*` audit fields, no update path — so it does NOT extend AuditFields
+ * (which carries `updated_*`).
+ */
+export interface KnowledgeRecordLink {
+  id: string
+  org_id: string
+  node_id: string
+  entity_slug: string
+  record_id: string
+  created_at: string
+  created_by: UserRef
+}
+
+/** A categorization handle. `slug` is unique within an org. */
+export interface KnowledgeLabel extends AuditFields {
+  id: string
+  org_id: string
+  name: string
+  slug: string
+  description?: string | null
+  color?: string | null
+  icon?: string | null
+}
+
+/** The node↔label association row. */
+export interface KnowledgeNodeLabel {
+  org_id: string
+  node_id: string
+  label_id: string
+  created_at: string
+  created_by: UserRef
+}
+
+// ============================================================================
+// Node requests
+// ============================================================================
+
+/** A typed edge from a node being created to an existing node (create-and-connect). */
+export interface InlineLinkRequest {
+  to_id: string
+  type: LinkType
+  description?: string
+}
+
+/**
+ * Create a node, optionally connecting it to the graph in one call. `label_ids`
+ * attaches existing labels; `links` creates edges FROM the new node. Both are
+ * applied atomically with the node insert.
+ */
+export interface CreateNodeRequest {
+  title: string
+  type: NodeType
+  status: NodeStatus
+  content?: string
+  file_id?: string
+  url?: string
+  summary?: string
+  /** Validity window (RFC3339). Omitted = unbounded (NULL). */
+  valid_from?: string
+  valid_until?: string
+  label_ids?: string[]
+  links?: InlineLinkRequest[]
+}
+
+/** Partial metadata update. Content is updated via the content methods, not here. */
+export interface UpdateNodeRequest {
+  title?: string
+  status?: NodeStatus
+  summary?: string
+  /**
+   * Validity window (RFC3339), tri-state: omit the key to leave unchanged, pass
+   * `null` to clear it back to unbounded (re-open validity), or a timestamp to
+   * set it. Setting `valid_until` to an instant ends a fact's validity.
+   */
+  valid_from?: string | null
+  valid_until?: string | null
+}
+
+/** Filters for listing nodes. */
+export interface ListNodesOptions extends ListOptions {
+  type?: NodeType
+  status?: NodeStatus
+  title?: string
+  'title[contains]'?: string
+  /** Keep only nodes carrying ANY of these labels (union). */
+  label_ids?: string[]
+  /** Created on/after this RFC3339 timestamp (inclusive). */
+  created_after?: string
+  /** Created on/before this RFC3339 timestamp (inclusive). */
+  created_before?: string
+  /** Updated on/after this RFC3339 timestamp (inclusive). */
+  updated_after?: string
+  /** Updated on/before this RFC3339 timestamp (inclusive). */
+  updated_before?: string
+  /** Validity boundary range filters (RFC3339) — filter on where a node's window start/end falls. */
+  valid_from_after?: string
+  valid_from_before?: string
+  valid_until_after?: string
+  valid_until_before?: string
+  /**
+   * Point-in-time validity filter (RFC3339): keep only nodes valid AT this
+   * instant (null-aware, half-open). Set `is_valid: false` to invert it (nodes
+   * INVALID at the instant). `is_valid` defaults to true.
+   */
+  is_valid_at?: string
+  is_valid?: boolean
+}
+
+// ── Content sub-resource ────────────────────────────────────────────────
+
+/** A node's raw body plus its line count. */
+export interface ContentResponse {
+  id: string
+  content: string
+  lines_total: number
+}
+
+export interface WriteContentResponse {
+  id: string
+  lines_total: number
+}
+
+/** A surgical anchored edit (mirrors Claude Code's `Edit`). */
+export interface EditContentRequest {
+  old_string: string
+  new_string: string
+  replace_all?: boolean
+}
+
+export interface EditContentResponse {
+  id: string
+  replacements: number
+  lines_total: number
+}
+
+// ── Within-node navigation: outline & grep ─────────────────────────────────
+
+/** One markdown heading in a node's outline, with the line range of its section. */
+export interface OutlineHeading {
+  level: number
+  title: string
+  line_start: number
+  line_end: number
+}
+
+/** One node's structural map. `headings` is empty for a body with no headings. */
+export interface NodeOutline {
+  node_id: string
+  title: string
+  lines_total: number
+  headings: OutlineHeading[]
+}
+
+/** Outline one or several nodes' bodies in a single call. */
+export interface OutlineRequest {
+  node_ids: string[]
+}
+
+export interface OutlineResponse {
+  results: NodeOutline[]
+}
+
+/** One grep hit: the matching line, the snippet's line range, and the cat -n snippet. */
+export interface ContentMatch {
+  line: number
+  line_start: number
+  line_end: number
+  snippet: string
+}
+
+/** One node's grep result. `match_count` is the true total; `matches` is capped. */
+export interface NodeContentMatches {
+  node_id: string
+  title: string
+  lines_total: number
+  match_count: number
+  truncated: boolean
+  matches: ContentMatch[]
+}
+
+/** Grep one or several node bodies. Substring by default; set `is_regex` for a regex. */
+export interface SearchContentRequest {
+  node_ids: string[]
+  pattern: string
+  is_regex?: boolean
+  is_case_sensitive?: boolean
+  context_lines?: number
+  max_matches_per_node?: number
+}
+
+export interface SearchContentResponse {
+  results: NodeContentMatches[]
+}
+
+// ── Search ───────────────────────────────────────────────────────────────
+
+/** Hybrid retrieval request. `match_mode` defaults to `keyword`. */
+export interface SearchNodesRequest {
+  query: string
+  match_mode?: MatchMode
+  type?: NodeType
+  status?: NodeStatus
+  /** Match nodes carrying ANY of these labels. */
+  label_ids?: string[]
+  /** Match nodes connected (either direction) to this node. */
+  linked_to_id?: string
+  /**
+   * Date-range filters (RFC3339). These only narrow the candidate set; results
+   * stay relevance-ordered, so a date filter never reorders hits.
+   */
+  created_after?: string
+  created_before?: string
+  updated_after?: string
+  updated_before?: string
+  /**
+   * Point-in-time validity filter (RFC3339): restrict hits to nodes valid AT
+   * this instant (or INVALID when `is_valid` is false; defaults to true). Narrows
+   * the candidate set only — ordering stays relevance-based.
+   */
+  is_valid_at?: string
+  is_valid?: boolean
+  page?: number
+  page_size?: number
+}
+
+// ── Neighbors ──────────────────────────────────────────────────────────────
+
+/** Options for a neighbors graph walk. */
+export interface NeighborsOptions {
+  direction?: NeighborDirection
+  /** Comma-separated link types to follow (e.g. "part_of,depends_on"). */
+  link_types?: string
+  depth?: number
+}
+
+export interface NeighborNode {
+  id: string
+  title: string
+  type: NodeType
+  status: NodeStatus
+  distance: number
+}
+
+export interface NeighborEdge {
+  id: string
+  from_id: string
+  to_id: string
+  type: LinkType
+}
+
+export interface NodeNeighborhood {
+  nodes: NeighborNode[]
+  edges: NeighborEdge[]
+}
+
+// ============================================================================
+// Graph (whole-org bulk read for the radiant graph view)
+// ============================================================================
+
+/**
+ * A lean node in the whole-graph payload — only what the graph renderer needs.
+ * `label_ids` are ordered by attachment time, so `label_ids[0]` is the "first"
+ * label (the one the UI colours the node by). `degree` is the in+out link count
+ * within the returned graph (drives node size).
+ */
+export interface KnowledgeGraphNode {
+  id: string
+  title: string
+  type: NodeType
+  status: NodeStatus
+  label_ids: string[]
+  degree: number
+}
+
+/** A lean directed edge in the whole-graph payload. */
+export interface KnowledgeGraphLink {
+  id: string
+  from_id: string
+  to_id: string
+  type: LinkType
+}
+
+/**
+ * The whole org graph in one payload: lean nodes + links, the full org label set
+ * (sent once — colours every node and powers the filter bar even when the graph
+ * is pruned), and `total`, the unfiltered org node count (lets the client decide
+ * whether to load the whole graph or switch to progressive/LOD loading).
+ */
+export interface KnowledgeGraph {
+  nodes: KnowledgeGraphNode[]
+  links: KnowledgeGraphLink[]
+  labels: KnowledgeLabel[]
+  total: number
+}
+
+/**
+ * Options for `getGraph`. `label_ids` prunes the graph to nodes carrying ANY of
+ * the given labels (union); omitted/empty returns the whole org graph.
+ */
+export interface GetGraphOptions {
+  label_ids?: string[]
+}
+
+// ============================================================================
+// Link requests
+// ============================================================================
+
+export interface CreateLinkRequest {
+  from_id: string
+  to_id: string
+  type: LinkType
+  description?: string
+}
+
+export interface UpdateLinkRequest {
+  type?: LinkType
+  description?: string
+}
+
+export interface ListLinksOptions extends ListOptions {
+  from_id?: string
+  to_id?: string
+  type?: LinkType
+  /** Created on/after this RFC3339 timestamp (inclusive). */
+  created_after?: string
+  /** Created on/before this RFC3339 timestamp (inclusive). */
+  created_before?: string
+  /** Updated on/after this RFC3339 timestamp (inclusive). */
+  updated_after?: string
+  /** Updated on/before this RFC3339 timestamp (inclusive). */
+  updated_before?: string
+}
+
+// ============================================================================
+// Record-link requests
+// ============================================================================
+
+export interface CreateRecordLinkRequest {
+  node_id: string
+  entity_slug: string
+  record_id: string
+}
+
+export interface ListRecordLinksOptions extends ListOptions {
+  node_id?: string
+  entity_slug?: string
+  record_id?: string
+}
+
+// ============================================================================
+// Label requests
+// ============================================================================
+
+export interface CreateLabelRequest {
+  name: string
+  slug: string
+  description?: string
+  color?: string
+  icon?: string
+}
+
+export interface UpdateLabelRequest {
+  name?: string
+  description?: string
+  color?: string
+  icon?: string
+}
+
+export interface ListLabelsOptions extends ListOptions {
+  slug?: string
+  name?: string
+  'name[contains]'?: string
+}
+
+// ============================================================================
+// Zod schemas (optional runtime validation for consumers who want it)
+// ============================================================================
+
+export const KnowledgeNodeMetadataSchema = z
+  .object({
+    id: z.string(),
+    org_id: z.string(),
+    title: z.string(),
+    type: z.enum(['markdown', 'file', 'url']),
+    status: z.enum(['draft', 'published', 'archived']),
+    embedding_model: z.string().nullish(),
+    embedded_at: z.string().nullish(),
+    file_id: z.string().nullish(),
+    url: z.string().nullish(),
+    summary: z.string().nullish(),
+    valid_from: z.string().nullish(),
+    valid_until: z.string().nullish(),
+  })
+  .merge(AuditFieldsSchema)
+
+export const KnowledgeNodeSchema = KnowledgeNodeMetadataSchema.extend({
+  content: z.string(),
+})
+
+export const KnowledgeNodeSearchResultSchema = KnowledgeNodeMetadataSchema.extend({
+  score: z.number(),
+})
+
+export const KnowledgeLinkSchema = z
+  .object({
+    id: z.string(),
+    org_id: z.string(),
+    from_id: z.string(),
+    to_id: z.string(),
+    type: z.enum([
+      'references',
+      'relates_to',
+      'depends_on',
+      'part_of',
+      'derived_from',
+      'contradicts',
+      'supports',
+      'duplicates',
+      'superseded_by',
+    ]),
+    description: z.string().nullish(),
+  })
+  .merge(AuditFieldsSchema)
+
+export const KnowledgeRecordLinkSchema = z.object({
+  id: z.string(),
+  org_id: z.string(),
+  node_id: z.string(),
+  entity_slug: z.string(),
+  record_id: z.string(),
+  created_at: z.string(),
+  created_by: UserRefSchema,
+})
+
+export const KnowledgeLabelSchema = z
+  .object({
+    id: z.string(),
+    org_id: z.string(),
+    name: z.string(),
+    slug: z.string(),
+    description: z.string().nullish(),
+    color: z.string().nullish(),
+    icon: z.string().nullish(),
+  })
+  .merge(AuditFieldsSchema)
+
+export const KnowledgeNodeLabelSchema = z.object({
+  org_id: z.string(),
+  node_id: z.string(),
+  label_id: z.string(),
+  created_at: z.string(),
+  created_by: UserRefSchema,
+})
+
+export const NodeNeighborhoodSchema = z.object({
+  nodes: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      type: z.enum(['markdown', 'file', 'url']),
+      status: z.enum(['draft', 'published', 'archived']),
+      distance: z.number(),
+    }),
+  ),
+  edges: z.array(
+    z.object({
+      id: z.string(),
+      from_id: z.string(),
+      to_id: z.string(),
+      type: z.string(),
+    }),
+  ),
+})