@proteos/sdk 0.18.1

package/src/auth/users.ts

@@ -0,0 +1,226 @@
+import type { ProteosClient } from '../client.js'
+import { PageIterator } from '../iterator.js'
+import type { ListResult } from '../types/common.js'
+import type {
+  ApiKey,
+  AssignRoleRequest,
+  CreateApiKeyRequest,
+  CreatedApiKey,
+  CreateUserRequest,
+  ListUserRoleAssignmentsOptions,
+  ListUsersOptions,
+  UpdateUserRequest,
+  User,
+  UserRoleAssignment,
+} from './types.js'
+
+const USERS_BASE_PATH = '/accounts/v1/users'
+
+/**
+ * Service for managing users.
+ * Handles user CRUD operations and role assignments.
+ */
+export interface UserService {
+  /**
+   * Lists users with optional filtering.
+   * Returns an async iterator that automatically handles pagination.
+   *
+   * @param options - Filter and pagination options
+   * @returns Async iterator over users
+   *
+   * @example
+   * ```ts
+   * // Iterate over all users
+   * for await (const user of service.list()) {
+   *   console.log(user.email);
+   * }
+   *
+   * // With filtering
+   * for await (const user of service.list({ email: 'john@example.com' })) {
+   *   console.log(user.given_name);
+   * }
+   * ```
+   */
+  list(options?: ListUsersOptions): PageIterator<User, ListUsersOptions>
+
+  /**
+   * Gets a single user by ID.
+   *
+   * @param id - User ID
+   * @returns The user
+   * @throws {ProteosError} If user not found (404)
+   */
+  get(id: string): Promise<User>
+
+  /**
+   * Creates a new user.
+   *
+   * @param request - User creation request
+   * @returns The created user
+   * @throws {ProteosError} If validation fails (400) or conflict (409)
+   *
+   * @example
+   * ```ts
+   * const user = await service.create({
+   *   given_name: 'John',
+   *   family_name: 'Doe',
+   *   email: 'john.doe@example.com',
+   * });
+   * ```
+   */
+  create(request: CreateUserRequest): Promise<User>
+
+  /**
+   * Updates an existing user.
+   *
+   * @param id - User ID
+   * @param request - Fields to update
+   * @returns The updated user
+   * @throws {ProteosError} If user not found (404) or validation fails (400)
+   */
+  update(id: string, request: UpdateUserRequest): Promise<User>
+
+  /**
+   * Fetches a single page of users.
+   *
+   * @param options - Filter and pagination options (including `page`)
+   * @returns A single page of users with pagination metadata
+   */
+  listPage(options?: ListUsersOptions): Promise<ListResult<User>>
+
+  /**
+   * Gets roles assigned to a user.
+   * Returns an async iterator that automatically handles pagination.
+   *
+   * @param userId - User ID
+   * @param options - Filter and pagination options
+   * @returns Async iterator over user role assignments
+   */
+  getRoles(
+    userId: string,
+    options?: ListUserRoleAssignmentsOptions,
+  ): PageIterator<UserRoleAssignment, ListUserRoleAssignmentsOptions>
+
+  /**
+   * Assigns a role to a user.
+   *
+   * @param userId - User ID
+   * @param request - Role assignment request
+   * @returns The created user role assignment
+   * @throws {ProteosError} If user or role not found (404)
+   */
+  assignRole(userId: string, request: AssignRoleRequest): Promise<UserRoleAssignment>
+
+  /**
+   * Removes a role from a user.
+   *
+   * @param userId - User ID
+   * @param roleSlug - Role slug to unassign
+   * @throws {ProteosError} If assignment not found (404)
+   */
+  unassignRole(userId: string, roleSlug: string): Promise<void>
+
+  /**
+   * Lists a user's API keys (display hints only — never tokens).
+   *
+   * @param userId - User ID, or `'me'` for the calling user
+   */
+  listApiKeys(userId: string): Promise<ApiKey[]>
+
+  /**
+   * Creates an API key for the user. The response carries the full token
+   * exactly once; it cannot be read again. Requires a JWT session — requests
+   * authenticated with an API key are rejected (403).
+   *
+   * @param userId - User ID, or `'me'` for the calling user
+   * @param request - Key name, optional org binding and expiry
+   */
+  createApiKey(userId: string, request: CreateApiKeyRequest): Promise<CreatedApiKey>
+
+  /**
+   * Deletes (revokes) an API key. Other services may keep accepting the key
+   * for up to their verification-cache TTL (~60s).
+   *
+   * @param userId - User ID, or `'me'` for the calling user
+   * @param keyId - API key ID
+   * @throws {ProteosError} If the key is not found under this user (404)
+   */
+  deleteApiKey(userId: string, keyId: string): Promise<void>
+}
+
+/**
+ * Implementation of UserService.
+ */
+export class UserServiceImpl implements UserService {
+  constructor(private readonly client: ProteosClient) {}
+
+  list(options: ListUsersOptions = {}): PageIterator<User, ListUsersOptions> {
+    return new PageIterator((opts) => this.listPage(opts), options)
+  }
+
+  async listPage(options: ListUsersOptions = {}): Promise<ListResult<User>> {
+    return this.client.requestWithQuery<ListResult<User>>('GET', USERS_BASE_PATH, options)
+  }
+
+  async get(id: string): Promise<User> {
+    return this.client.request<User>('GET', `${USERS_BASE_PATH}/${id}`)
+  }
+
+  async create(request: CreateUserRequest): Promise<User> {
+    return this.client.request<User>('POST', USERS_BASE_PATH, request)
+  }
+
+  async update(id: string, request: UpdateUserRequest): Promise<User> {
+    return this.client.request<User>('PATCH', `${USERS_BASE_PATH}/${id}`, request)
+  }
+
+  getRoles(
+    userId: string,
+    options: ListUserRoleAssignmentsOptions = {},
+  ): PageIterator<UserRoleAssignment, ListUserRoleAssignmentsOptions> {
+    return new PageIterator((opts) => this.fetchRolesPage(userId, opts), options)
+  }
+
+  async assignRole(userId: string, request: AssignRoleRequest): Promise<UserRoleAssignment> {
+    return this.client.request<UserRoleAssignment>(
+      'POST',
+      `${USERS_BASE_PATH}/${userId}/roles`,
+      request,
+    )
+  }
+
+  async unassignRole(userId: string, roleSlug: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${USERS_BASE_PATH}/${userId}/roles/${roleSlug}`)
+  }
+
+  async listApiKeys(userId: string): Promise<ApiKey[]> {
+    const response = await this.client.request<{ data: ApiKey[] }>(
+      'GET',
+      `${USERS_BASE_PATH}/${userId}/api-keys`,
+    )
+    return response.data
+  }
+
+  async createApiKey(userId: string, request: CreateApiKeyRequest): Promise<CreatedApiKey> {
+    return this.client.request<CreatedApiKey>(
+      'POST',
+      `${USERS_BASE_PATH}/${userId}/api-keys`,
+      request,
+    )
+  }
+
+  async deleteApiKey(userId: string, keyId: string): Promise<void> {
+    await this.client.request<void>('DELETE', `${USERS_BASE_PATH}/${userId}/api-keys/${keyId}`)
+  }
+
+  private async fetchRolesPage(
+    userId: string,
+    options: ListUserRoleAssignmentsOptions,
+  ): Promise<ListResult<UserRoleAssignment>> {
+    return this.client.requestWithQuery<ListResult<UserRoleAssignment>>(
+      'GET',
+      `${USERS_BASE_PATH}/${userId}/roles`,
+      options,
+    )
+  }
+}

package/src/client.ts

@@ -0,0 +1,441 @@
+import { type EventSourceMessage, fetchEventSource } from '@microsoft/fetch-event-source'
+import { ProteosError, parseErrorResponse } from './errors.js'
+import { toQueryParams } from './http/query-params.js'
+import {
+  type ClientOptions,
+  type RequestOptions,
+  type ResolvedClientOptions,
+  resolveOptions,
+} from './types/options.js'
+
+/** One parsed Server-Sent-Events frame yielded by {@link ProteosClient.streamEvents}. */
+export interface SseFrame {
+  /** The frame `id:` line — Proteos services use the per-stream monotonic seq. */
+  id?: string
+  /** The frame `event:` line — the named event type. */
+  event?: string
+  /** The frame `data:` line — the raw payload (typically JSON). */
+  data: string
+}
+
+/** Options for opening an SSE stream. */
+export interface StreamOptions {
+  /** Abort to tear the stream down (the normal stop path). */
+  signal?: AbortSignal
+}
+
+/** True when an error is an AbortError (a stream's normal teardown). */
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'AbortError'
+}
+
+/**
+ * Base HTTP client for all Proteos services.
+ * Handles authentication, request/response formatting, and error handling.
+ */
+export class ProteosClient {
+  private readonly options: ResolvedClientOptions
+
+  /**
+   * Creates a new ProteosClient instance.
+   *
+   * @param options - Client configuration options
+   *
+   * @example
+   * ```ts
+   * // With static token
+   * const client = new ProteosClient({
+   *   baseUrl: 'https://api.proteos.ai',
+   *   token: 'your-api-token',
+   * });
+   *
+   * // With dynamic token provider
+   * const client = new ProteosClient({
+   *   baseUrl: 'https://api.proteos.ai',
+   *   tokenProvider: async () => {
+   *     return await authService.getAccessToken();
+   *   },
+   * });
+   * ```
+   */
+  constructor(options: ClientOptions) {
+    this.options = resolveOptions(options)
+  }
+
+  /**
+   * Returns the base URL configured for this client.
+   */
+  get baseUrl(): string {
+    return this.options.baseUrl
+  }
+
+  /**
+   * Gets the current authentication token.
+   * Calls tokenProvider if available, otherwise returns static token.
+   */
+  private async getToken(): Promise<string | undefined> {
+    if (this.options.tokenProvider) {
+      return await this.options.tokenProvider()
+    }
+    return this.options.token
+  }
+
+  /**
+   * Builds the headers for a request.
+   */
+  private async buildHeaders(requestOptions?: RequestOptions): Promise<Headers> {
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      ...this.options.headers,
+      ...requestOptions?.headers,
+    })
+
+    const token = await this.getToken()
+    if (token) {
+      headers.set('Authorization', `Bearer ${token}`)
+    }
+
+    return headers
+  }
+
+  /**
+   * Creates an AbortSignal with timeout.
+   */
+  private createTimeoutSignal(requestOptions?: RequestOptions): AbortSignal {
+    const timeout = requestOptions?.timeout ?? this.options.timeout
+
+    // Combine user signal with timeout signal if both exist
+    if (requestOptions?.signal) {
+      const controller = new AbortController()
+
+      // Abort when user signal aborts
+      requestOptions.signal.addEventListener('abort', () => {
+        controller.abort(requestOptions.signal?.reason)
+      })
+
+      // Abort on timeout
+      const timeoutId = setTimeout(() => {
+        controller.abort(new Error(`Request timeout after ${timeout}ms`))
+      }, timeout)
+
+      // Clean up timeout if aborted early
+      controller.signal.addEventListener('abort', () => {
+        clearTimeout(timeoutId)
+      })
+
+      return controller.signal
+    }
+
+    return AbortSignal.timeout(timeout)
+  }
+
+  /**
+   * Performs an HTTP request and decodes the JSON response.
+   *
+   * @param method - HTTP method (GET, POST, PATCH, DELETE, etc.)
+   * @param path - Request path (appended to baseUrl)
+   * @param body - Request body (will be JSON-serialized)
+   * @param requestOptions - Optional request configuration
+   * @returns Decoded response body
+   * @throws {ProteosError} If the response status is >= 400
+   */
+  async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    requestOptions?: RequestOptions,
+  ): Promise<T> {
+    return this.requestWithQuery(method, path, undefined, body, requestOptions)
+  }
+
+  /**
+   * Performs an HTTP request with query parameters.
+   *
+   * @param method - HTTP method
+   * @param path - Request path
+   * @param query - Query parameters object
+   * @param body - Request body
+   * @param requestOptions - Optional request configuration
+   * @returns Decoded response body
+   * @throws {ProteosError} If the response status is >= 400
+   */
+  async requestWithQuery<T, Q extends object = object>(
+    method: string,
+    path: string,
+    query?: Q,
+    body?: unknown,
+    requestOptions?: RequestOptions,
+  ): Promise<T> {
+    let url = `${this.options.baseUrl}${path}`
+
+    if (query) {
+      const params = toQueryParams(query)
+      const queryString = params.toString()
+      if (queryString) {
+        url += `?${queryString}`
+      }
+    }
+
+    const headers = await this.buildHeaders(requestOptions)
+    const signal = this.createTimeoutSignal(requestOptions)
+
+    const response = await this.options.fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : null,
+      signal,
+    })
+
+    if (response.status >= 400) {
+      throw await parseErrorResponse(response)
+    }
+
+    // No content response
+    if (response.status === 204) {
+      return undefined as T
+    }
+
+    // Parse JSON response
+    const text = await response.text()
+    if (!text) {
+      return undefined as T
+    }
+
+    try {
+      return JSON.parse(text) as T
+    } catch {
+      throw new ProteosError(
+        `Failed to parse response as JSON: ${text.slice(0, 100)}`,
+        response.status,
+        'parse_error',
+      )
+    }
+  }
+
+  /**
+   * Performs a multipart form request (for file uploads).
+   *
+   * @param method - HTTP method
+   * @param path - Request path
+   * @param formData - FormData instance with files and fields
+   * @param requestOptions - Optional request configuration
+   * @returns Decoded response body
+   * @throws {ProteosError} If the response status is >= 400
+   */
+  async requestMultipart<T>(
+    method: string,
+    path: string,
+    formData: FormData,
+    requestOptions?: RequestOptions,
+  ): Promise<T> {
+    const url = `${this.options.baseUrl}${path}`
+
+    // Don't set Content-Type - let fetch set it with boundary
+    const headers = new Headers({
+      Accept: 'application/json',
+      ...this.options.headers,
+      ...requestOptions?.headers,
+    })
+
+    const token = await this.getToken()
+    if (token) {
+      headers.set('Authorization', `Bearer ${token}`)
+    }
+
+    const signal = this.createTimeoutSignal(requestOptions)
+
+    const response = await this.options.fetch(url, {
+      method,
+      headers,
+      body: formData,
+      signal,
+    })
+
+    if (response.status >= 400) {
+      throw await parseErrorResponse(response)
+    }
+
+    if (response.status === 204) {
+      return undefined as T
+    }
+
+    return (await response.json()) as T
+  }
+
+  /**
+   * Performs an HTTP request and returns the raw response.
+   * Used for downloading files or streaming responses.
+   *
+   * @param method - HTTP method
+   * @param path - Request path
+   * @param body - Request body
+   * @param requestOptions - Optional request configuration
+   * @returns Object with response body stream and full Response object
+   * @throws {ProteosError} If the response status is >= 400
+   */
+  async requestRaw(
+    method: string,
+    path: string,
+    body?: unknown,
+    requestOptions?: RequestOptions,
+  ): Promise<{ body: ReadableStream<Uint8Array> | null; response: Response }> {
+    const url = `${this.options.baseUrl}${path}`
+
+    const headers = await this.buildHeaders(requestOptions)
+    const signal = this.createTimeoutSignal(requestOptions)
+
+    const response = await this.options.fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : null,
+      signal,
+    })
+
+    if (response.status >= 400) {
+      throw await parseErrorResponse(response)
+    }
+
+    return {
+      body: response.body,
+      response,
+    }
+  }
+
+  /**
+   * Opens a Server-Sent-Events stream and yields each frame as it arrives.
+   *
+   * Built on `@microsoft/fetch-event-source` (not the browser-native
+   * `EventSource`, which can't set an `Authorization` header) so the bearer token
+   * is attached like any other request. The library tracks `Last-Event-ID` and
+   * reconnects with exponential backoff on transient errors; a 4xx is fatal and
+   * rejects. The stream runs until the caller's `AbortSignal` fires.
+   *
+   * The token is resolved once at stream start; teardown is the caller's signal.
+   *
+   * @param path - Request path (appended to baseUrl)
+   * @param requestOptions - Optional request configuration (signal)
+   * @returns Async generator of parsed {@link SseFrame}s
+   * @throws {ProteosError} On a non-retryable (4xx) response
+   */
+  async *streamEvents(
+    path: string,
+    requestOptions?: StreamOptions,
+  ): AsyncGenerator<SseFrame, void, unknown> {
+    const url = `${this.options.baseUrl}${path}`
+
+    const headers: Record<string, string> = { ...this.options.headers }
+    const token = await this.getToken()
+    if (token) {
+      headers.Authorization = `Bearer ${token}`
+    }
+
+    // Bridge fetch-event-source's callbacks into an async generator: producer
+    // pushes frames onto a queue, the consumer (this generator) drains it,
+    // parking on a promise whenever the queue is empty.
+    const queue: SseFrame[] = []
+    let wake: (() => void) | null = null
+    let finished = false
+    let failure: unknown
+
+    const notify = () => {
+      wake?.()
+      wake = null
+    }
+    const push = (frame: SseFrame) => {
+      queue.push(frame)
+      notify()
+    }
+    const finish = (error?: unknown) => {
+      if (error !== undefined) failure = error
+      finished = true
+      notify()
+    }
+
+    const controller = new AbortController()
+    const onExternalAbort = () => controller.abort()
+    if (requestOptions?.signal) {
+      if (requestOptions.signal.aborted) controller.abort()
+      else requestOptions.signal.addEventListener('abort', onExternalAbort, { once: true })
+    }
+
+    const streaming = fetchEventSource(url, {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+      fetch: this.options.fetch,
+      // Keep streaming when the tab is backgrounded (default would disconnect).
+      openWhenHidden: true,
+      onopen: async (response: Response) => {
+        if (response.status >= 400) {
+          throw await parseErrorResponse(response)
+        }
+      },
+      onmessage: (message: EventSourceMessage) => {
+        push({
+          id: message.id || undefined,
+          event: message.event || undefined,
+          data: message.data,
+        })
+      },
+      onerror: (error: unknown) => {
+        // Abort + 4xx are fatal (rethrow to stop). Everything else is transient
+        // — return a backoff so the library reconnects (Last-Event-ID resumes).
+        if (isAbortError(error)) throw error
+        if (error instanceof ProteosError && error.httpStatus >= 400 && error.httpStatus < 500) {
+          throw error
+        }
+        return 2000
+      },
+    })
+      .then(() => finish())
+      .catch((error: unknown) => finish(error))
+
+    try {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift() as SseFrame
+          continue
+        }
+        if (finished) break
+        await new Promise<void>((resolve) => {
+          wake = resolve
+        })
+      }
+      if (failure !== undefined && !isAbortError(failure)) throw failure
+    } finally {
+      controller.abort()
+      requestOptions?.signal?.removeEventListener('abort', onExternalAbort)
+      await streaming.catch(() => {})
+    }
+  }
+
+  /**
+   * Opens an authenticated WebSocket to a service path and resolves once it is
+   * open.
+   *
+   * The browser-native `WebSocket` can't set an `Authorization` header, so the
+   * access token is passed via the `bearer` subprotocol (`["bearer", token]`),
+   * which the gateway lifts back into the auth header — the same token resolved
+   * for every other request. The `http(s)` base URL is rewritten to `ws(s)`.
+   *
+   * @param path - Request path (appended to baseUrl), including any query string
+   * @returns The open WebSocket
+   */
+  async openWebSocket(path: string): Promise<WebSocket> {
+    const wsBaseUrl = this.options.baseUrl.replace(/^http/, 'ws')
+    const url = `${wsBaseUrl}${path}`
+
+    const token = await this.getToken()
+    const socket = token ? new WebSocket(url, ['bearer', token]) : new WebSocket(url)
+
+    await new Promise<void>((resolve, reject) => {
+      socket.onopen = () => resolve()
+      socket.onerror = () => reject(new ProteosError('WebSocket connection failed', 0, 'ws_error'))
+    })
+    // Clear the bootstrap handlers so the caller owns the socket cleanly.
+    socket.onopen = null
+    socket.onerror = null
+    return socket
+  }
+}