@proteos/sdk 0.18.1

package/src/events/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Types for the event-service (read/admin view over the Redis-Streams
+ * event bus). Field names mirror the Go JSON shapes in
+ * packages/go/model/events.
+ */
+
+/** Whether a topic is a normal event stream or a dead-letter stream. */
+export type TopicKind = 'event' | 'dead_letter'
+
+/** A consumer group registered on a topic's stream. */
+export interface ConsumerGroup {
+  name: string
+  consumers: number
+  pending: number
+  lag: number
+}
+
+/**
+ * A topic — a read-only projection of one Redis stream scoped to the caller's
+ * org. Discovered live from the bus; reflects only the retention window.
+ */
+export interface Topic {
+  /** Logical topic name, e.g. "record.contact.events" or "...events.dlq". */
+  name: string
+  /** Friendly label from the catalog, or `name` when unknown. */
+  display_name: string
+  kind: TopicKind
+  /** For a dead-letter topic, the source topic its entries belong to. */
+  source_topic?: string
+  event_count: number
+  /** ISO timestamp of the newest entry, when the stream is non-empty. */
+  last_event_at?: string
+  consumer_groups: ConsumerGroup[]
+}
+
+/** A single event — a read-only projection of one Redis stream entry. */
+export interface PlatformEvent {
+  /** Redis stream entry id ("<ms>-<seq>") — the cursor for paging / tailing. */
+  stream_id: string
+  /** Application event id (UUID) from the envelope. */
+  id: string
+  org_id: string
+  topic: string
+  type: string
+  key?: string
+  /** Event body — JSON in practice; surfaced verbatim. */
+  payload: unknown
+  headers?: Record<string, string>
+  dispatched_at: string
+}
+
+/** Options for reading the last-N events on a topic. */
+export interface ListEventsOptions {
+  /** Max events to return (newest first). */
+  limit?: number
+  /** Stream-id cursor; returns entries strictly older than it. */
+  before?: string
+}
+
+/** Body for publishing a test event onto a topic. */
+export interface PublishEventRequest {
+  type: string
+  key?: string
+  payload?: unknown
+}
+
+/** Outcome of redriving a dead-letter stream back to its source topic. */
+export interface RedriveResult {
+  source_topic: string
+  redriven: number
+}
+
+/** Options for a live tail. */
+export interface TailOptions {
+  /** Abort the tail (stop streaming and release the connection). */
+  signal?: AbortSignal
+}

package/src/functions/actions.ts

@@ -0,0 +1,95 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type { Action, InvokeActionResponse, ListActionsOptions } from './types.js'
+
+const ACTIONS_BASE_PATH = '/functions/v1/actions'
+
+/**
+ * Service for managing deployed actions (function-service).
+ *
+ * Actions are user-invokable operations. `params` and `returns` follow the
+ * same `Attribute` schema language as entity attributes — the UI form
+ * renderer consumes them directly.
+ */
+export interface ActionService {
+  /**
+   * Lists deployed actions as an async iterator.
+   */
+  list(options?: ListActionsOptions): PageIterator<Action, ListActionsOptions>
+
+  /**
+   * Fetches a single page of actions.
+   */
+  listPage(options?: ListActionsOptions): Promise<ListResult<Action>>
+
+  /**
+   * Gets a single action by slug. The returned `Action` carries the full
+   * `params` and `returns` schemas, suitable for driving an invocation form.
+   *
+   * @throws {ProteosError} If the action is not found (404).
+   */
+  get(slug: string): Promise<Action>
+
+  /**
+   * Invokes a global-scoped action. Returns the unwrapped `result`
+   * payload — the wire envelope `{ result }` is unwrapped by the SDK.
+   *
+   * @throws {ProteosError} On guest validation failures (400, `GUEST_ERROR`),
+   *   timeouts (504, `TIMEOUT`), traps (500, `TRAP`), or other failure kinds.
+   */
+  invokeGlobal(slug: string, params: Record<string, unknown>): Promise<unknown>
+
+  /**
+   * Invokes an entity-scoped action against a specific record. Returns the
+   * unwrapped `result` payload.
+   */
+  invokeEntity(
+    entitySlug: string,
+    recordId: string,
+    slug: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown>
+}
+
+/**
+ * Implementation of ActionService.
+ */
+export class ActionServiceImpl implements ActionService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListActionsOptions = {}): PageIterator<Action, ListActionsOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListActionsOptions = {}): Promise<ListResult<Action>> {
+    return this.client.requestWithQuery<ListResult<Action>>('GET', ACTIONS_BASE_PATH, options)
+  }
+
+  async get(slug: string): Promise<Action> {
+    return this.client.request<Action>('GET', `${ACTIONS_BASE_PATH}/${slug}`)
+  }
+
+  async invokeGlobal(slug: string, params: Record<string, unknown>): Promise<unknown> {
+    const response = await this.client.request<InvokeActionResponse>(
+      'POST',
+      `${ACTIONS_BASE_PATH}/${slug}/invoke`,
+      params,
+    )
+    return response.result
+  }
+
+  async invokeEntity(
+    entitySlug: string,
+    recordId: string,
+    slug: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    const response = await this.client.request<InvokeActionResponse>(
+      'POST',
+      `/functions/v1/entities/${entitySlug}/records/${recordId}/actions/${slug}/invoke`,
+      params,
+    )
+    return response.result
+  }
+}

package/src/functions/index.ts

@@ -0,0 +1,32 @@
+import type { ProteosClient } from '../client.js'
+import { type ActionService, ActionServiceImpl } from './actions.js'
+
+/**
+ * Facade for the function-service (deployed actions + hooks).
+ *
+ * @example
+ * ```ts
+ * const client = new ProteosClient({ baseUrl, tokenProvider });
+ * const functions = new FunctionsClient(client);
+ * const action = await functions.actions.get('mark-as-signed');
+ * const result = await functions.actions.invokeEntity(
+ *   'document', recordId, 'mark-as-signed', { signatureType: 'ELECTRONIC' },
+ * );
+ * ```
+ */
+export class FunctionsClient {
+  readonly actions: ActionService
+
+  constructor(client: ProteosClient) {
+    this.actions = new ActionServiceImpl(client)
+  }
+}
+
+// Re-export service interfaces
+export type { ActionService } from './actions.js'
+
+// Re-export types
+export type { Action, ActionScope, InvokeActionResponse, ListActionsOptions } from './types.js'
+
+// Re-export Zod schemas
+export { ActionSchema, ActionScopeSchema } from './types.js'

package/src/functions/types.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+
+import { type Attribute, AttributeSchema } from '../meta/types.js'
+import { type AuditFields, AuditFieldsSchema } from '../types/common.js'
+
+/**
+ * Scope of an action. `entity`-scoped actions are invoked against a
+ * specific record; `global` actions take no record context.
+ */
+export type ActionScope = 'entity' | 'global'
+
+export const ActionScopeSchema = z.enum(['entity', 'global'])
+
+/**
+ * Deployable, user-invokable operation. Mirrors `functionsmodel.Action`
+ * in the Go SDK. `params` and `returns` reuse the same `Attribute` schema
+ * language as entity attributes — the renderer consumes them directly.
+ */
+export interface Action extends AuditFields {
+  slug: string
+  org_id: string
+  module_slug: string
+  scope: ActionScope
+  /** Present only when `scope === 'entity'`. */
+  entity?: string
+  name: string
+  is_active: boolean
+  /**
+   * When true (global actions only), the action is invokable on the
+   * unauthenticated public endpoint
+   * `POST /functions/v1/public/orgs/{orgId}/actions/{slug}/invoke`.
+   */
+  is_public: boolean
+  file_id: string
+  params: Attribute[]
+  returns: Attribute[]
+}
+
+export const ActionSchema = AuditFieldsSchema.extend({
+  slug: z.string(),
+  org_id: z.string(),
+  module_slug: z.string(),
+  scope: ActionScopeSchema,
+  entity: z.string().optional(),
+  name: z.string(),
+  is_active: z.boolean(),
+  file_id: z.string(),
+  params: z.array(AttributeSchema),
+  returns: z.array(AttributeSchema),
+})
+
+/**
+ * Options for listing actions.
+ */
+export interface ListActionsOptions {
+  page?: number
+  page_size?: number
+  sort?: string
+  scope?: ActionScope
+  module_slug?: string
+  entity?: string
+  is_active?: boolean
+}
+
+/**
+ * Wire envelope returned by the invoke endpoints. The SDK unwraps `result`
+ * before returning to callers; this type is exported for completeness.
+ */
+export interface InvokeActionResponse {
+  result: unknown
+}

package/src/http/index.ts

@@ -0,0 +1,2 @@
+export type { QueryObject, QueryValue } from './query-params.js'
+export { buildUrl, toQueryParams, toQueryString } from './query-params.js'

package/src/http/query-params.ts

@@ -0,0 +1,106 @@
+/**
+ * Value types that can be converted to query parameters.
+ */
+export type QueryValue = string | number | boolean | null | undefined
+
+/**
+ * Object that can be converted to query parameters.
+ * Supports nested objects (which are skipped during conversion).
+ */
+export type QueryObject = Record<string, QueryValue | QueryValue[] | Record<string, unknown>>
+
+/**
+ * Converts an object to URLSearchParams for use in query strings.
+ * Handles nested objects by flattening them (skips complex nested structures).
+ * Skips null and undefined values.
+ *
+ * @param obj - Object to convert
+ * @returns URLSearchParams instance
+ *
+ * @example
+ * ```ts
+ * toQueryParams({ page: 1, name: 'test', is_active: true })
+ * // => URLSearchParams { page: '1', name: 'test', is_active: 'true' }
+ *
+ * toQueryParams({ filter: { slug: 'my-slug' } })
+ * // => URLSearchParams {} (nested objects are skipped)
+ * ```
+ */
+export function toQueryParams(obj: object | undefined | null): URLSearchParams {
+  const params = new URLSearchParams()
+
+  if (!obj) {
+    return params
+  }
+
+  for (const [key, value] of Object.entries(obj)) {
+    appendQueryParam(params, key, value as QueryValue | QueryValue[] | Record<string, unknown>)
+  }
+
+  return params
+}
+
+/**
+ * Appends a single value to URLSearchParams.
+ */
+function appendQueryParam(
+  params: URLSearchParams,
+  key: string,
+  value: QueryValue | QueryValue[] | Record<string, unknown>,
+): void {
+  // Skip null and undefined
+  if (value === null || value === undefined) {
+    return
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (item !== null && item !== undefined) {
+        params.append(key, String(item))
+      }
+    }
+    return
+  }
+
+  // Skip nested objects (complex types)
+  if (typeof value === 'object') {
+    return
+  }
+
+  // Convert primitives to string
+  params.set(key, String(value))
+}
+
+/**
+ * Converts a URLSearchParams instance to a query string.
+ * Returns empty string if no parameters.
+ *
+ * @param params - URLSearchParams to convert
+ * @returns Query string (without leading '?')
+ */
+export function toQueryString(params: URLSearchParams): string {
+  const str = params.toString()
+  return str
+}
+
+/**
+ * Builds a full URL with query parameters.
+ *
+ * @param baseUrl - Base URL (may already have query params)
+ * @param path - Path to append
+ * @param query - Query parameters to add
+ * @returns Full URL string
+ */
+export function buildUrl(baseUrl: string, path: string, query?: object): string {
+  const url = new URL(path, baseUrl)
+
+  if (query) {
+    const params = toQueryParams(query)
+    params.forEach((value, key) => {
+      url.searchParams.append(key, value)
+    })
+  }
+
+  return url.toString()
+}