@proteos/sdk 0.18.1

package/src/data/index.ts

@@ -0,0 +1,53 @@
+import type { ProteosClient } from '../client.js'
+import { type QueryService, QueryServiceImpl } from './queries.js'
+import { type RecordService, RecordServiceImpl } from './records.js'
+
+/**
+ * Facade for the data-service (records + raw-SQL query API).
+ *
+ * Usage:
+ * ```ts
+ * const client = new ProteosClient({ baseUrl, tokenProvider });
+ * const data = new DataClient(client);
+ * const page = await data.records.listPage('customer');
+ * const result = await data.queries.execute('SELECT id, stage FROM opportunity');
+ * ```
+ */
+export class DataClient {
+  readonly records: RecordService
+  readonly queries: QueryService
+
+  constructor(client: ProteosClient) {
+    this.records = new RecordServiceImpl(client)
+    this.queries = new QueryServiceImpl(client)
+  }
+}
+
+// Re-export service interfaces
+// Re-export types
+export type {
+  QueryExecuteMeta,
+  QueryExecuteResponse,
+  QueryRow,
+  QueryService,
+  QueryValidateMeta,
+  QueryValidateResponse,
+} from './queries.js'
+export type { RecordService } from './records.js'
+export type {
+  BatchTransactionError,
+  BatchTransactionStatus,
+  BatchUpsertRecordsResponse,
+  BatchUpsertTransaction,
+  BatchUpsertTransactionResult,
+  ListRecordsOptions,
+  RecordData,
+} from './types.js'
+
+// Re-export Zod schemas
+export {
+  BatchTransactionErrorSchema,
+  BatchUpsertRecordsResponseSchema,
+  BatchUpsertTransactionResultSchema,
+  BatchUpsertTransactionSchema,
+} from './types.js'

package/src/data/queries.ts

@@ -0,0 +1,66 @@
+import type { ProteosClient } from '../client.js'
+
+const QUERY_BASE_PATH = '/data/v1/query'
+
+/**
+ * A single row from a query result. Keys match the result-set columns
+ * (camelCase, with `id`/`created_at`/`updated_at` reserved). The data-service
+ * hoists JSONB columns into nested objects, so values can be primitives,
+ * nested records, or arrays.
+ */
+export type QueryRow = Record<string, unknown>
+
+export interface QueryExecuteMeta {
+  columns: string[]
+  items: number
+  limit_applied: number
+  /** Only present when `true`. */
+  was_default_limit_applied?: boolean
+  execution_time_ms: number
+}
+
+export interface QueryExecuteResponse {
+  data: QueryRow[]
+  meta?: QueryExecuteMeta
+}
+
+export interface QueryValidateMeta {
+  limit_applied: number
+  was_default_limit_applied?: boolean
+}
+
+export interface QueryValidateResponse {
+  valid: boolean
+  /** The SQL the server would execute (entity-rewritten, schema-qualified). */
+  rewritten_sql?: string
+  tables?: string[]
+  meta?: QueryValidateMeta
+}
+
+/**
+ * Service for the raw-SQL query endpoint of the data-service.
+ *
+ * Accepts SELECT-only Postgres SQL with bare attribute references; the
+ * server rewrites bare attributes into JSONB accessors against the
+ * tenant's schema and runs per-table OpenFGA authorization checks.
+ */
+export interface QueryService {
+  /** Executes the SQL and returns the result rows + meta. */
+  execute(sql: string): Promise<QueryExecuteResponse>
+  /** Parses + authorizes the SQL without running it. */
+  validate(sql: string): Promise<QueryValidateResponse>
+}
+
+export class QueryServiceImpl implements QueryService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async execute(sql: string): Promise<QueryExecuteResponse> {
+    return this.client.request<QueryExecuteResponse>('POST', `${QUERY_BASE_PATH}/execute`, { sql })
+  }
+
+  async validate(sql: string): Promise<QueryValidateResponse> {
+    return this.client.request<QueryValidateResponse>('POST', `${QUERY_BASE_PATH}/validate`, {
+      sql,
+    })
+  }
+}

package/src/data/records.ts

@@ -0,0 +1,122 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  BatchUpsertRecordsResponse,
+  BatchUpsertTransaction,
+  ListRecordsOptions,
+  RecordData,
+} from './types.js'
+
+const RECORDS_BASE_PATH = '/data/v1/records'
+const BATCH_RECORDS_BASE_PATH = '/data/v1/batch/records'
+
+/**
+ * Service for managing records (per-entity data rows) via the data-service.
+ *
+ * Records are opaque JSON objects whose schema is defined per-entity in the
+ * metadata service. An entity must be registered (via metadata-service, which
+ * in turn provisions a Postgres table) before records for it can be created.
+ */
+export interface RecordService {
+  /**
+   * Lists records for an entity as an async iterator. Pages are 0-indexed
+   * (first page is 0); `PageIterator` starts there automatically.
+   */
+  list(
+    entitySlug: string,
+    options?: ListRecordsOptions,
+  ): PageIterator<RecordData, ListRecordsOptions>
+
+  /**
+   * Fetches a single page of records.
+   */
+  listPage(entitySlug: string, options?: ListRecordsOptions): Promise<ListResult<RecordData>>
+
+  /**
+   * Gets a single record by id.
+   * @throws {ProteosError} If the record is not found (404).
+   */
+  get(entitySlug: string, id: string): Promise<RecordData>
+
+  /**
+   * Creates a new record for the given entity.
+   */
+  create(entitySlug: string, data: RecordData): Promise<RecordData>
+
+  /**
+   * Partially updates a record.
+   */
+  update(entitySlug: string, id: string, data: Partial<RecordData>): Promise<RecordData>
+
+  /**
+   * Deletes a record.
+   */
+  delete(entitySlug: string, id: string): Promise<void>
+
+  /**
+   * Batch-upserts records. Each transaction succeeds/fails independently;
+   * the response contains a per-transaction status so callers (e.g. import
+   * flows) can render per-row feedback.
+   */
+  batchUpsert(
+    entitySlug: string,
+    transactions: BatchUpsertTransaction[],
+  ): Promise<BatchUpsertRecordsResponse>
+}
+
+/**
+ * Implementation of RecordService.
+ */
+export class RecordServiceImpl implements RecordService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(
+    entitySlug: string,
+    options: ListRecordsOptions = {},
+  ): PageIterator<RecordData, ListRecordsOptions> {
+    return new PageIterator((opts) => this.listPage(entitySlug, opts), options)
+  }
+
+  async listPage(
+    entitySlug: string,
+    options: ListRecordsOptions = {},
+  ): Promise<ListResult<RecordData>> {
+    return this.client.requestWithQuery<ListResult<RecordData>>(
+      'GET',
+      `${RECORDS_BASE_PATH}/${entitySlug}`,
+      options,
+    )
+  }
+
+  async get(entitySlug: string, id: string): Promise<RecordData> {
+    return this.client.request<RecordData>('GET', `${RECORDS_BASE_PATH}/${entitySlug}/${id}`)
+  }
+
+  async create(entitySlug: string, data: RecordData): Promise<RecordData> {
+    return this.client.request<RecordData>('POST', `${RECORDS_BASE_PATH}/${entitySlug}`, data)
+  }
+
+  async update(entitySlug: string, id: string, data: Partial<RecordData>): Promise<RecordData> {
+    return this.client.request<RecordData>(
+      'PATCH',
+      `${RECORDS_BASE_PATH}/${entitySlug}/${id}`,
+      data,
+    )
+  }
+
+  async delete(entitySlug: string, id: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${RECORDS_BASE_PATH}/${entitySlug}/${id}`)
+  }
+
+  async batchUpsert(
+    entitySlug: string,
+    transactions: BatchUpsertTransaction[],
+  ): Promise<BatchUpsertRecordsResponse> {
+    return this.client.request<BatchUpsertRecordsResponse>(
+      'POST',
+      `${BATCH_RECORDS_BASE_PATH}/${entitySlug}/upsert`,
+      transactions,
+    )
+  }
+}

package/src/data/types.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod'
+
+/**
+ * A record is an open-shape JSON object whose keys are the entity's attribute
+ * names plus system fields (`id`, `created_at`, `updated_at`, `created_by`,
+ * `updated_by`). Because attributes vary per entity, values are typed as `any`
+ * at the SDK layer — consumers narrow or cast as needed.
+ */
+export type RecordData = Record<string, any>
+
+/**
+ * Options for listing records.
+ *
+ * Sorting: use `sort: "field:asc"` for single-column; pipe-separated for
+ * multi-column (`"field1:asc|field2:desc"`). Defaults to `created_at:desc`.
+ *
+ * Arbitrary filter keys pass through as query params. Supported operators
+ * (via bracket syntax) include `[eq]`, `[ne]`, `[gt]`, `[gte]`, `[lt]`,
+ * `[lte]`, `[in]` (pipe-separated), `[not_in]`, `[contains]`, `[starts_with]`,
+ * `[ends_with]`, `[empty]`, `[not_empty]`. Missing operator defaults to `[eq]`.
+ */
+export interface ListRecordsOptions {
+  /** Page number (0-indexed). First page is 0. */
+  page?: number
+  /** Number of items per page (default: 20 per backend) */
+  page_size?: number
+  /**
+   * Sort spec. Format: `"field:direction"`, or pipe-separated for multi-column:
+   * `"field1:asc|field2:desc"`. Direction is `asc` | `desc`.
+   */
+  sort?: string
+  /** Arbitrary attribute filters (flat query-string params). */
+  [key: string]: unknown
+}
+
+// ============================================================================
+// Batch operations
+// ============================================================================
+
+/**
+ * One transaction within a batch operation.
+ * `transaction_id` is client-supplied so you can match results back to your
+ * source rows (used e.g. by import flows).
+ */
+export interface BatchUpsertTransaction {
+  transaction_id: string
+  data: Record<string, unknown>
+}
+
+export type BatchTransactionStatus = 'success' | 'error'
+
+export interface BatchTransactionError {
+  code: string
+  message: string
+}
+
+export interface BatchUpsertTransactionResult {
+  transaction_id: string
+  status: BatchTransactionStatus
+  record?: RecordData
+  error?: BatchTransactionError
+}
+
+export interface BatchUpsertRecordsResponse {
+  results: BatchUpsertTransactionResult[]
+}
+
+// Zod schemas for runtime validation (optional, for consumers who want it)
+
+export const BatchUpsertTransactionSchema = z.object({
+  transaction_id: z.string(),
+  data: z.record(z.unknown()),
+})
+
+export const BatchTransactionErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+})
+
+export const BatchUpsertTransactionResultSchema = z.object({
+  transaction_id: z.string(),
+  status: z.enum(['success', 'error']),
+  record: z.record(z.unknown()).optional(),
+  error: BatchTransactionErrorSchema.optional(),
+})
+
+export const BatchUpsertRecordsResponseSchema = z.object({
+  results: z.array(BatchUpsertTransactionResultSchema),
+})

package/src/errors.ts

@@ -0,0 +1,148 @@
+/**
+ * Common error codes returned by the Proteos API.
+ */
+export const ErrorCode = {
+  NOT_FOUND: 'not_found',
+  UNAUTHORIZED: 'unauthorized',
+  FORBIDDEN: 'forbidden',
+  BAD_REQUEST: 'bad_request',
+  CONFLICT: 'conflict',
+  INTERNAL_SERVER_ERROR: 'internal_server_error',
+  INVALID_PAYLOAD: 'invalid_payload',
+  INVALID_PERSONA: 'invalid_persona',
+} as const
+
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode]
+
+/**
+ * Error returned by the Proteos API.
+ * Contains HTTP status code, error code, and human-readable message.
+ */
+export class ProteosError extends Error {
+  /** HTTP status code of the response */
+  readonly httpStatus: number
+  /** API error code (e.g., 'not_found', 'unauthorized') */
+  readonly code: ErrorCodeType | string
+
+  constructor(message: string, httpStatus: number, code: ErrorCodeType | string) {
+    super(message)
+    this.name = 'ProteosError'
+    this.httpStatus = httpStatus
+    this.code = code
+
+    // V8-specific API for cleaner stack traces; not present in all runtimes
+    const v8Capture = (Error as unknown as { captureStackTrace?: (t: object, c: unknown) => void })
+      .captureStackTrace
+    if (v8Capture) v8Capture(this, this.constructor)
+  }
+
+  /**
+   * Returns a formatted string representation of the error.
+   */
+  override toString(): string {
+    return `${this.code}: ${this.message} (HTTP ${this.httpStatus})`
+  }
+}
+
+/**
+ * Type guard to check if an error is a ProteosError.
+ */
+export function isProteosError(error: unknown): error is ProteosError {
+  return error instanceof ProteosError
+}
+
+/**
+ * Type guard to check if an error is a 404 Not Found error.
+ */
+export function isNotFound(error: unknown): error is ProteosError {
+  return isProteosError(error) && error.httpStatus === 404
+}
+
+/**
+ * Type guard to check if an error is a 401 Unauthorized error.
+ */
+export function isUnauthorized(error: unknown): error is ProteosError {
+  return isProteosError(error) && error.httpStatus === 401
+}
+
+/**
+ * Type guard to check if an error is a 403 Forbidden error.
+ */
+export function isForbidden(error: unknown): error is ProteosError {
+  return isProteosError(error) && error.httpStatus === 403
+}
+
+/**
+ * Type guard to check if an error is a 400 Bad Request error.
+ */
+export function isBadRequest(error: unknown): error is ProteosError {
+  return isProteosError(error) && error.httpStatus === 400
+}
+
+/**
+ * Type guard to check if an error is a 409 Conflict error.
+ */
+export function isConflict(error: unknown): error is ProteosError {
+  return isProteosError(error) && error.httpStatus === 409
+}
+
+/**
+ * Maps HTTP status codes to default error codes.
+ */
+export function getDefaultErrorCode(httpStatus: number): ErrorCodeType | string {
+  switch (httpStatus) {
+    case 400:
+      return ErrorCode.BAD_REQUEST
+    case 401:
+      return ErrorCode.UNAUTHORIZED
+    case 403:
+      return ErrorCode.FORBIDDEN
+    case 404:
+      return ErrorCode.NOT_FOUND
+    case 409:
+      return ErrorCode.CONFLICT
+    default:
+      return ErrorCode.INTERNAL_SERVER_ERROR
+  }
+}
+
+/**
+ * Response shape for API error responses.
+ */
+export interface ApiErrorResponse {
+  code?: string
+  message?: string
+}
+
+/**
+ * Parses an error response from the API and creates a ProteosError.
+ */
+export async function parseErrorResponse(response: Response): Promise<ProteosError> {
+  const httpStatus = response.status
+  let code: string = getDefaultErrorCode(httpStatus)
+  let message = 'Unknown error'
+
+  try {
+    const body = await response.text()
+
+    // Try to parse as JSON
+    try {
+      const json = JSON.parse(body) as ApiErrorResponse
+      if (json.code) {
+        code = json.code
+      }
+      if (json.message) {
+        message = json.message
+      } else {
+        message = body || `HTTP ${httpStatus}`
+      }
+    } catch {
+      // Not JSON, use body as message
+      message = body.trim() || `HTTP ${httpStatus}`
+    }
+  } catch {
+    message = `HTTP ${httpStatus}`
+  }
+
+  return new ProteosError(message, httpStatus, code)
+}

package/src/events/index.ts

@@ -0,0 +1,172 @@
+import type { ProteosClient } from '../client.js'
+import type {
+  ListEventsOptions,
+  PlatformEvent,
+  PublishEventRequest,
+  RedriveResult,
+  TailOptions,
+  Topic,
+} from './types.js'
+
+const EVENTS_BASE_PATH = '/events/v1'
+
+// A live tail is a long-poll; override the client's default request timeout so
+// it isn't aborted mid-stream. ~24h is well under the setTimeout overflow bound
+// and acts as a practical cap on a single tail session. Real teardown is the
+// caller's AbortSignal.
+const TAIL_TIMEOUT_MS = 24 * 60 * 60 * 1000
+
+/**
+ * Facade for event-service: a read/admin view over the Redis-Streams bus.
+ * Everything is topic-centric, so the surface lives on `topics`.
+ *
+ * ```ts
+ * const events = new EventsClient(client)
+ * const topics = await events.topics.list()
+ * const recent = await events.topics.events('record.contact.events', { limit: 50 })
+ * for await (const msg of events.topics.tail('record.contact.events', { signal })) {
+ *   // append msg
+ * }
+ * ```
+ */
+export class EventsClient {
+  readonly topics: TopicService
+
+  constructor(client: ProteosClient) {
+    this.topics = new TopicServiceImpl(client)
+  }
+}
+
+/** Topic discovery, event reads + live tail, and admin actions. */
+export interface TopicService {
+  /** List the caller-org's topics. */
+  list(): Promise<Topic[]>
+  /** Read the most-recent events on a topic (newest first). */
+  events(topic: string, options?: ListEventsOptions): Promise<PlatformEvent[]>
+  /**
+   * Live-tail new events on a topic until the AbortSignal fires. Yields each
+   * event as it arrives (chunked NDJSON under the hood).
+   */
+  tail(topic: string, options?: TailOptions): AsyncGenerator<PlatformEvent, void, unknown>
+  /** Publish a test event onto a topic — delivered to real consumers. */
+  publish(topic: string, request: PublishEventRequest): Promise<PlatformEvent>
+  /** Move a dead-letter stream back to its source topic for re-processing. */
+  redrive(topic: string): Promise<RedriveResult>
+  /** Empty a topic's stream (keeps consumer groups). Destructive. */
+  purge(topic: string): Promise<void>
+}
+
+class TopicServiceImpl implements TopicService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async list(): Promise<Topic[]> {
+    const response = await this.client.request<{ data: Topic[] }>(
+      'GET',
+      `${EVENTS_BASE_PATH}/topics`,
+    )
+    return response.data ?? []
+  }
+
+  async events(topic: string, options: ListEventsOptions = {}): Promise<PlatformEvent[]> {
+    const response = await this.client.requestWithQuery<{ data: PlatformEvent[] }, ListEventsOptions>(
+      'GET',
+      `${EVENTS_BASE_PATH}/topics/${encodeURIComponent(topic)}/events`,
+      options,
+    )
+    return response.data ?? []
+  }
+
+  async *tail(topic: string, options: TailOptions = {}): AsyncGenerator<PlatformEvent, void, unknown> {
+    const path = `${EVENTS_BASE_PATH}/topics/${encodeURIComponent(topic)}/events?follow=true`
+    let body: ReadableStream<Uint8Array> | null
+    try {
+      ;({ body } = await this.client.requestRaw('GET', path, undefined, {
+        timeout: TAIL_TIMEOUT_MS,
+        ...(options.signal ? { signal: options.signal } : {}),
+        headers: { Accept: 'application/x-ndjson' },
+      }))
+    } catch (error) {
+      if (isAbort(error)) return
+      throw error
+    }
+    if (!body) return
+
+    const reader = body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        buffer += decoder.decode(value, { stream: true })
+        let newlineIndex = buffer.indexOf('\n')
+        while (newlineIndex !== -1) {
+          const line = buffer.slice(0, newlineIndex).trim()
+          buffer = buffer.slice(newlineIndex + 1)
+          const event = parseLine(line)
+          if (event) yield event
+          newlineIndex = buffer.indexOf('\n')
+        }
+      }
+      const remainder = parseLine(buffer.trim())
+      if (remainder) yield remainder
+    } catch (error) {
+      if (!isAbort(error)) throw error
+    } finally {
+      reader.releaseLock()
+      void body.cancel().catch(() => {})
+    }
+  }
+
+  async publish(topic: string, request: PublishEventRequest): Promise<PlatformEvent> {
+    return this.client.request<PlatformEvent>(
+      'POST',
+      `${EVENTS_BASE_PATH}/topics/${encodeURIComponent(topic)}/events`,
+      request,
+    )
+  }
+
+  async redrive(topic: string): Promise<RedriveResult> {
+    return this.client.request<RedriveResult>(
+      'POST',
+      `${EVENTS_BASE_PATH}/topics/${encodeURIComponent(topic)}/redrive`,
+    )
+  }
+
+  async purge(topic: string): Promise<void> {
+    await this.client.request<void>(
+      'POST',
+      `${EVENTS_BASE_PATH}/topics/${encodeURIComponent(topic)}/purge`,
+    )
+  }
+}
+
+/** True when an error is an AbortError (the tail's normal stop path). */
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'AbortError'
+}
+
+/**
+ * Parses one NDJSON line into a PlatformEvent, returning null for a blank or
+ * unparseable line. A single bad frame should be skipped, not tear down the
+ * whole tail.
+ */
+function parseLine(line: string): PlatformEvent | null {
+  if (!line) return null
+  try {
+    return JSON.parse(line) as PlatformEvent
+  } catch {
+    return null
+  }
+}
+
+export type {
+  ConsumerGroup,
+  ListEventsOptions,
+  PlatformEvent,
+  PublishEventRequest,
+  RedriveResult,
+  TailOptions,
+  Topic,
+  TopicKind,
+} from './types.js'