@proteos/sdk 0.18.1

package/src/meta/variables.ts

@@ -0,0 +1,98 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  CreateVariableRequest,
+  ListVariablesOptions,
+  UpdateVariableRequest,
+  Variable,
+} from './types.js'
+
+const VARIABLES_BASE_PATH = '/meta/v1/variables'
+
+/**
+ * Service for managing configuration and secret variables.
+ * Variables store key-value pairs scoped to modules.
+ */
+export interface VariableService {
+  /**
+   * Lists variables with optional filtering.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over variables
+   */
+  list(options?: ListVariablesOptions): PageIterator<Variable, ListVariablesOptions>
+
+  /**
+   * Fetches a single page of variables.
+   * Useful for paginated UI frameworks (e.g. React Query's useInfiniteQuery).
+   */
+  listPage(options?: ListVariablesOptions): Promise<ListResult<Variable>>
+
+  /**
+   * Gets a single variable by ID.
+   *
+   * @param id - Variable ID
+   * @returns The variable
+   * @throws {ProteosError} If variable not found (404)
+   */
+  get(id: string): Promise<Variable>
+
+  /**
+   * Creates a new variable.
+   *
+   * @param request - Variable creation request
+   * @returns The created variable
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   */
+  create(request: CreateVariableRequest): Promise<Variable>
+
+  /**
+   * Updates an existing variable.
+   *
+   * @param id - Variable ID
+   * @param request - Fields to update
+   * @returns The updated variable
+   * @throws {ProteosError} If variable not found (404) or validation fails (400)
+   */
+  update(id: string, request: UpdateVariableRequest): Promise<Variable>
+
+  /**
+   * Deletes a variable.
+   *
+   * @param id - Variable ID
+   * @throws {ProteosError} If variable not found (404)
+   */
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Implementation of VariableService.
+ */
+export class VariableServiceImpl implements VariableService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListVariablesOptions = {}): PageIterator<Variable, ListVariablesOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListVariablesOptions = {}): Promise<ListResult<Variable>> {
+    return this.client.requestWithQuery<ListResult<Variable>>('GET', VARIABLES_BASE_PATH, options)
+  }
+
+  async get(id: string): Promise<Variable> {
+    return this.client.request<Variable>('GET', `${VARIABLES_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateVariableRequest): Promise<Variable> {
+    return this.client.request<Variable>('POST', VARIABLES_BASE_PATH, request)
+  }
+
+  async update(id: string, request: UpdateVariableRequest): Promise<Variable> {
+    return this.client.request<Variable>('PATCH', `${VARIABLES_BASE_PATH}/${id}`, request)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${VARIABLES_BASE_PATH}/${id}`)
+  }
+}

package/src/storage/files.ts

@@ -0,0 +1,183 @@
+import type { ProteosClient } from '../client.js'
+import type { CreateFileMetadata, FileVersionContent, StorageFile } from './types.js'
+
+const FILES_BASE_PATH = '/storage/v1/files'
+
+/**
+ * Service for storing and retrieving files via the storage-service.
+ *
+ * The storage-service is one-blob-per-id (no directories); each `upload` creates
+ * a brand-new file. A `file`-typed record attribute stores only the resulting
+ * `{ id, name }` (a `FileRef`); size and content type are resolved on read via
+ * {@link FileService.get}.
+ */
+export interface FileService {
+  /**
+   * Uploads bytes and creates a new file. Returns the created file (including
+   * `current_version.size_in_bytes` and `content_type`). The caller derives the
+   * `FileRef { id, name }` it stores on the record from the result.
+   *
+   * `name` defaults to the `File`'s own name; `contentType` to its MIME type.
+   */
+  upload(file: File, options?: { name?: string; contentType?: string }): Promise<StorageFile>
+
+  /**
+   * Creates a file's metadata only (no bytes) — the first step of the upload-URL
+   * flow for large files. The returned file is not yet persisted; mint an upload URL
+   * with {@link FileService.createUploadUrl} and PUT the bytes to it.
+   */
+  create(metadata: CreateFileMetadata): Promise<StorageFile>
+
+  /**
+   * Mints a short-lived upload URL for a file. The bytes are PUT directly to this URL
+   * (raw body, no auth) — keeping large files off the SDK/MCP path. Single-use, ~3 min.
+   */
+  createUploadUrl(id: string): Promise<{ url: string; expires_at: string }>
+
+  /**
+   * Triggers content extraction for the file's current version. Asynchronous: returns
+   * a `processing` row (or cached `ready` content); poll {@link FileService.getContent}
+   * for the terminal status.
+   */
+  parse(id: string, options?: { parser?: string; force?: boolean }): Promise<FileVersionContent>
+
+  /**
+   * Fetches the parsed content of the file's current version.
+   * @throws {ProteosError} If the file has never been parsed (404).
+   */
+  getContent(id: string): Promise<FileVersionContent>
+
+  /**
+   * Fetches a file's metadata by id (name, content type, current version size).
+   * @throws {ProteosError} If the file is not found (404).
+   */
+  get(id: string): Promise<StorageFile>
+
+  /**
+   * Mints a short-lived public download URL for a file (the token in the URL is
+   * the sole credential — no auth header needed). Default: single-use, ≈5 min
+   * TTL, suitable for click-to-download. `allowsMultiUse` mints a token that
+   * survives repeated GETs (≈1 h TTL) for consumers that probe the URL before
+   * downloading.
+   */
+  createDownloadUrl(
+    id: string,
+    options?: { allowsMultiUse?: boolean },
+  ): Promise<{ url: string; expires_at: string }>
+
+  /**
+   * Downloads the file's current version as a Blob (authenticated). Prefer
+   * {@link FileService.createDownloadUrl} for browser click-to-download.
+   */
+  download(id: string): Promise<Blob>
+}
+
+/**
+ * Implementation of FileService.
+ */
+export class FileServiceImpl implements FileService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async upload(
+    file: File,
+    options?: { name?: string; contentType?: string },
+  ): Promise<StorageFile> {
+    const metadata: CreateFileMetadata = {
+      name: options?.name ?? file.name,
+      content_type: options?.contentType ?? file.type ?? 'application/octet-stream',
+    }
+
+    // The storage-service reads multipart parts in order: `metadata` (JSON)
+    // first, then `file` (bytes). FormData preserves append order, so the
+    // metadata Blob MUST be appended before the file.
+    const formData = new FormData()
+    formData.append('metadata', new Blob([JSON.stringify(metadata)], { type: 'application/json' }))
+    formData.append('file', file, metadata.name)
+
+    const response = await this.client.requestMultipart<{ data: StorageFile }>(
+      'POST',
+      FILES_BASE_PATH,
+      formData,
+    )
+    return response.data
+  }
+
+  async create(metadata: CreateFileMetadata): Promise<StorageFile> {
+    const formData = new FormData()
+    formData.append(
+      'metadata',
+      new Blob(
+        [
+          JSON.stringify({
+            name: metadata.name,
+            content_type: metadata.content_type ?? 'application/octet-stream',
+          }),
+        ],
+        { type: 'application/json' },
+      ),
+    )
+    const response = await this.client.requestMultipart<{ data: StorageFile }>(
+      'POST',
+      FILES_BASE_PATH,
+      formData,
+    )
+    return response.data
+  }
+
+  async createUploadUrl(id: string): Promise<{ url: string; expires_at: string }> {
+    const response = await this.client.request<{ data: { url: string; expires_at: string } }>(
+      'POST',
+      `${FILES_BASE_PATH}/${id}/generate-upload-url`,
+    )
+    return response.data
+  }
+
+  async parse(
+    id: string,
+    options?: { parser?: string; force?: boolean },
+  ): Promise<FileVersionContent> {
+    const response = await this.client.request<{ data: FileVersionContent }>(
+      'POST',
+      `${FILES_BASE_PATH}/${id}/parse`,
+      options ?? {},
+    )
+    return response.data
+  }
+
+  async getContent(id: string): Promise<FileVersionContent> {
+    const response = await this.client.request<{ data: FileVersionContent }>(
+      'GET',
+      `${FILES_BASE_PATH}/${id}/content`,
+    )
+    return response.data
+  }
+
+  async get(id: string): Promise<StorageFile> {
+    const response = await this.client.request<{ data: StorageFile }>(
+      'GET',
+      `${FILES_BASE_PATH}/${id}`,
+    )
+    return response.data
+  }
+
+  async createDownloadUrl(
+    id: string,
+    options?: { allowsMultiUse?: boolean },
+  ): Promise<{ url: string; expires_at: string }> {
+    const body =
+      options?.allowsMultiUse !== undefined
+        ? { allows_multi_use: options.allowsMultiUse }
+        : undefined
+    const response = await this.client.request<{ data: { url: string; expires_at: string } }>(
+      'POST',
+      `${FILES_BASE_PATH}/${id}/generate-download-url`,
+      body,
+    )
+    return response.data
+  }
+
+  async download(id: string): Promise<Blob> {
+    const { response } = await this.client.requestRaw('GET', `${FILES_BASE_PATH}/${id}/download`)
+    return await response.blob()
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,33 @@
+import type { ProteosClient } from '../client.js'
+import { type FileService, FileServiceImpl } from './files.js'
+
+/**
+ * Facade for the storage-service (file upload / download / metadata).
+ *
+ * Usage:
+ * ```ts
+ * const client = new ProteosClient({ baseUrl, tokenProvider });
+ * const storage = new StorageClient(client);
+ * const file = await storage.files.upload(picked); // -> { id, name, ... }
+ * const { url } = await storage.files.createDownloadUrl(file.id);
+ * ```
+ */
+export class StorageClient {
+  readonly files: FileService
+
+  constructor(client: ProteosClient) {
+    this.files = new FileServiceImpl(client)
+  }
+}
+
+// Re-export service interface
+export type { FileService } from './files.js'
+
+// Re-export types
+export type {
+  CreateFileMetadata,
+  FileVersionContent,
+  ParseStatus,
+  StorageFile,
+  StorageFileVersion,
+} from './types.js'

package/src/storage/types.ts

@@ -0,0 +1,70 @@
+/**
+ * A version of a stored file. Each file has one or more versions; the file's
+ * `current_version` points at the latest. Size is carried here, not on the
+ * file. Mirrors the Go `storagemodel.Version`.
+ */
+export interface StorageFileVersion {
+  id: string
+  number: number
+  file_id: string
+  size_in_bytes: number
+  hash: string
+  created_at: string
+  last_accessed_at: string
+}
+
+/**
+ * A stored file in the storage-service. The blob bytes live behind `id`; the
+ * size and content type are resolved here (size via `current_version`). Mirrors
+ * the Go `storagemodel.File`.
+ */
+export interface StorageFile {
+  id: string
+  org_id?: string | null
+  name: string
+  content_type: string
+  current_version: StorageFileVersion | null
+  is_deleted: boolean
+  is_persisted: boolean
+  is_locked: boolean
+  created_at: string
+  updated_at: string
+}
+
+/**
+ * Metadata sent alongside the bytes when creating a file. The storage-service
+ * reads this as the ordered `metadata` multipart part (before the `file` part).
+ */
+export interface CreateFileMetadata {
+  name: string
+  content_type?: string
+}
+
+/**
+ * Lifecycle of a version's parsed content. A parse is asynchronous: the row is
+ * created `processing`, then flips to `ready` (with content) or `failed` (with an
+ * error). Poll {@link FileService.getContent} for the terminal status.
+ */
+export type ParseStatus = 'pending' | 'processing' | 'ready' | 'failed'
+
+/**
+ * The parsed/extracted content of a file version — the cache produced by
+ * {@link FileService.parse} and read via {@link FileService.getContent}. This is the
+ * extracted text/markdown, NOT the raw bytes (use {@link FileService.download} for
+ * those). Mirrors the Go `storagemodel.FileVersionContent`.
+ */
+export interface FileVersionContent {
+  id: string
+  version_id: string
+  file_id: string
+  org_id?: string | null
+  format: string // markdown | text
+  content: string
+  parser?: string // model | document_ai | agent
+  model?: string
+  status: ParseStatus
+  error?: string | null
+  parsed_at?: string | null
+  created_at: string
+  updated_at: string
+}

package/src/types/common.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod'
+
+/**
+ * Pagination metadata from list responses.
+ * Field names match the backend wire format exactly.
+ */
+export interface ResponseMeta {
+  /** Current page number (0-indexed across all services). */
+  page: number
+  /** Number of items per page */
+  page_size: number
+  /** Total number of items across all pages */
+  items_total: number
+  /** Total number of pages */
+  pages_total: number
+}
+
+/**
+ * Zod schema for ResponseMeta validation.
+ */
+export const ResponseMetaSchema = z.object({
+  page: z.number(),
+  page_size: z.number(),
+  items_total: z.number(),
+  pages_total: z.number(),
+})
+
+/**
+ * Generic paginated response wrapper.
+ */
+export interface ListResult<T> {
+  meta: ResponseMeta
+  data: T[]
+}
+
+/**
+ * Creates a Zod schema for ListResult with a given item schema.
+ */
+export function createListResultSchema<T>(itemSchema: z.ZodType<T>) {
+  return z.object({
+    meta: ResponseMetaSchema,
+    data: z.array(itemSchema),
+  })
+}
+
+/**
+ * Base list options with pagination and sorting.
+ */
+export interface ListOptions {
+  /** Page number (0-indexed). First page is 0. */
+  page?: number
+  /** Number of items per page (default: 100) */
+  page_size?: number
+  /** Field to sort by */
+  sort_by?: string
+  /** Sort direction */
+  sort_direction?: 'asc' | 'desc'
+}
+
+/**
+ * Common timestamp fields for entities.
+ */
+export interface Timestamps {
+  /** ISO 8601 timestamp when the entity was created */
+  created_at: string
+  /** ISO 8601 timestamp when the entity was last updated */
+  updated_at: string
+}
+
+/**
+ * The kind of user a {@link UserRef} points at. `person` is a human; `agent`
+ * is an AI actor; `api` is a non-interactive client (reserved). The `"platform"`
+ * sentinel id (system/bootstrap writes) carries `person`.
+ */
+export type UserType = 'person' | 'agent' | 'api'
+
+/**
+ * A reference to a platform user — the value stored by every `user` attribute
+ * (including `created_by`/`updated_by`). `id` is the platform user id (or the
+ * `"platform"` sentinel for system writes); `type` is the user kind. The people
+ * picker resolves and filters on `id`.
+ */
+export interface UserRef {
+  type: UserType
+  id: string
+}
+
+/**
+ * Zod schema for a UserRef value.
+ */
+export const UserRefSchema = z.object({
+  type: z.enum(['person', 'agent', 'api']),
+  id: z.string(),
+})
+
+/**
+ * Sentinel id stored in created_by/updated_by for writes that didn't originate
+ * from a real user (bootstrap / system). Mirrors the backend's
+ * `common.PlatformUserId`.
+ */
+export const PLATFORM_USER_ID = 'platform'
+
+/**
+ * A reference to a stored file — the value stored by every `file` attribute.
+ * `id` is the storage-service file id; `name` is the denormalised filename the
+ * record carries so it has a human label without a storage round-trip. Size and
+ * content type are resolved from the storage-service by `id` on read. Mirrors
+ * the backend's `common.FileRef`.
+ */
+export interface FileRef {
+  id: string
+  name: string
+}
+
+/**
+ * Zod schema for a FileRef value.
+ */
+export const FileRefSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+/**
+ * Common audit fields for entities. `created_by`/`updated_by` hold a
+ * {@link UserRef} for the user who made the change (the `"platform"` sentinel
+ * id for system writes).
+ */
+export interface AuditFields extends Timestamps {
+  /** Who created the entity (the "platform" sentinel id for system writes). */
+  created_by: UserRef
+  /** Who last updated the entity (the "platform" sentinel id for system writes). */
+  updated_by: UserRef
+}
+
+/**
+ * Zod schema for audit fields validation.
+ */
+export const AuditFieldsSchema = z.object({
+  created_at: z.string(),
+  updated_at: z.string(),
+  created_by: UserRefSchema,
+  updated_by: UserRefSchema,
+})

package/src/types/index.ts

@@ -0,0 +1,28 @@
+export type {
+  AuditFields,
+  FileRef,
+  ListOptions,
+  ListResult,
+  ResponseMeta,
+  Timestamps,
+  UserRef,
+  UserType,
+} from './common.js'
+
+export {
+  AuditFieldsSchema,
+  createListResultSchema,
+  FileRefSchema,
+  PLATFORM_USER_ID,
+  ResponseMetaSchema,
+  UserRefSchema,
+} from './common.js'
+
+export type {
+  ClientOptions,
+  RequestOptions,
+  ResolvedClientOptions,
+  TokenProvider,
+} from './options.js'
+
+export { DEFAULT_OPTIONS, resolveOptions } from './options.js'

package/src/types/options.ts

@@ -0,0 +1,95 @@
+/**
+ * Token provider function for dynamic authentication.
+ * Can return a token synchronously or asynchronously.
+ */
+export type TokenProvider = () => string | Promise<string>
+
+/**
+ * Configuration options for the ProteosClient.
+ */
+export interface ClientOptions {
+  /**
+   * Base URL for API requests.
+   * Example: 'https://api.proteos.ai'
+   */
+  baseUrl: string
+
+  /**
+   * Static bearer token for authentication.
+   * Use this for simple authentication scenarios.
+   */
+  token?: string
+
+  /**
+   * Dynamic token provider function.
+   * Called before each request to get the current token.
+   * Takes precedence over static token if both are provided.
+   * Useful for token refresh scenarios.
+   */
+  tokenProvider?: TokenProvider
+
+  /**
+   * Request timeout in milliseconds.
+   * Default: 30000 (30 seconds)
+   */
+  timeout?: number
+
+  /**
+   * Custom fetch implementation.
+   * Useful for testing or environments without native fetch.
+   * Default: global fetch
+   */
+  fetch?: typeof fetch
+
+  /**
+   * Custom headers to include in all requests.
+   * Authorization header is set automatically from token/tokenProvider.
+   */
+  headers?: Record<string, string>
+}
+
+/**
+ * Internal resolved options with defaults applied.
+ */
+export interface ResolvedClientOptions {
+  baseUrl: string
+  token?: string
+  tokenProvider?: TokenProvider
+  timeout: number
+  fetch: typeof fetch
+  headers: Record<string, string>
+}
+
+/**
+ * Default client options.
+ */
+export const DEFAULT_OPTIONS = {
+  timeout: 30000,
+  headers: {},
+} as const
+
+/**
+ * Resolves client options by applying defaults.
+ */
+export function resolveOptions(options: ClientOptions): ResolvedClientOptions {
+  return {
+    baseUrl: options.baseUrl.replace(/\/$/, ''), // Remove trailing slash
+    ...(options.token !== undefined ? { token: options.token } : {}),
+    ...(options.tokenProvider !== undefined ? { tokenProvider: options.tokenProvider } : {}),
+    timeout: options.timeout ?? DEFAULT_OPTIONS.timeout,
+    fetch: (options.fetch ?? globalThis.fetch).bind(globalThis),
+    headers: { ...DEFAULT_OPTIONS.headers, ...options.headers },
+  }
+}
+
+/**
+ * Options for individual requests.
+ */
+export interface RequestOptions {
+  /** Request timeout in milliseconds (overrides client default) */
+  timeout?: number
+  /** Additional headers for this request */
+  headers?: Record<string, string>
+  /** AbortSignal for request cancellation */
+  signal?: AbortSignal
+}