@ycadence/sdk 0.0.0-stage → 0.2.0

package/src/client.ts

@@ -0,0 +1,550 @@
+/**
+ * The YCadence client.
+ *
+ * Shared by the CLI, the MCP server and anyone integrating from TypeScript, so
+ * there is one place that knows how to talk to the API — how errors are shaped,
+ * how paging works, how a key is presented, when a request is safe to retry.
+ * Three separate implementations of that would disagree, and the disagreement
+ * would surface as "the CLI works but the MCP server does not".
+ */
+
+import { type ApiFailure, createError, RequestIntercepted, YCadenceError } from './errors'
+import { buildPath, isIdempotentMethod, OPERATIONS, type OperationId } from './operations'
+import { paginate } from './pagination'
+import type {
+  CreateViewInput,
+  CreateWorkItemInput,
+  Cycle,
+  CycleProgress,
+  Health,
+  ImportInput,
+  ImportPreview,
+  ImportRun,
+  IntakeItem,
+  Label,
+  ListWorkItemsOptions,
+  Me,
+  Page,
+  Project,
+  State,
+  SubmitIntakeInput,
+  SubmitIntakeResult,
+  TriageInput,
+  TriageResult,
+  UpdateWorkItemInput,
+  View,
+  WorkItem,
+  WorkItemDetail,
+} from './types'
+import { SDK_VERSION } from './version'
+
+export interface RetryOptions {
+  /** Attempts after the first. Default 2. `0` turns retrying off. */
+  retries?: number
+  /** First backoff, doubled each attempt, with jitter. Default 250ms. */
+  baseDelayMs?: number
+  /** Ceiling for one wait, including a server's `Retry-After`. Default 8s. */
+  maxDelayMs?: number
+}
+
+/** What happened to one HTTP exchange; for logging. Never carries credentials. */
+export interface ResponseInfo {
+  method: string
+  path: string
+  status: number
+  requestId: string | undefined
+  durationMs: number
+  attempt: number
+  replayed: boolean
+}
+
+export interface ClientOptions {
+  /** e.g. https://ycadence.example.com. Trailing slashes are tolerated. */
+  baseUrl: string
+  apiKey: string
+  /**
+   * A Google identity token for an instance behind IAP or an authenticated
+   * Cloud Run service, sent as `Authorization: Bearer`. The transport's
+   * credential and the product's are different things and travel in different
+   * headers: the key always goes in `x-api-key`.
+   *
+   * A function is called before every request, because these tokens last
+   * about an hour and a long-running caller — the MCP server — outlives one.
+   */
+  identityToken?: string | (() => string | undefined | Promise<string | undefined>)
+  /** Defaults to 30s. A request that hangs forever is worse than one that fails. */
+  timeoutMs?: number
+  fetch?: typeof globalThis.fetch
+  /**
+   * Retries for 429, 5xx, timeouts and network errors. Only GET requests, and
+   * mutations sent with an idempotency key, are retried: repeating any other
+   * write could apply it twice.
+   */
+  retry?: RetryOptions
+  /** Prepended to the default `User-Agent`, e.g. `ycadence-cli/0.2.0`. */
+  userAgent?: string
+  /** Called after every response, including ones that are retried. */
+  onResponse?: (info: ResponseInfo) => void
+  /** Injected for tests; defaults to a timer. */
+  sleep?: (ms: number) => Promise<void>
+}
+
+/** Per-call options for any request. */
+export interface RequestOptions {
+  /**
+   * Sent as `Idempotency-Key` on a mutation, which also makes the mutation
+   * safe to retry. Servers that do not support the header ignore it.
+   */
+  idempotencyKey?: string
+  /**
+   * The version the caller last saw, sent as `If-Match: "<version>"`. A server
+   * that versions the resource answers 409 `version_conflict` or 412 when it
+   * has moved on; one that does not ignores the header.
+   */
+  expectedVersion?: number | string
+  signal?: AbortSignal
+  /** Overrides the client's retry count for this call. */
+  retries?: number
+}
+
+const DEFAULT_RETRY: Required<RetryOptions> = { retries: 2, baseDelayMs: 250, maxDelayMs: 8_000 }
+
+export class YCadenceClient {
+  private readonly baseUrl: string
+  private readonly apiKey: string
+  private readonly identityToken: ClientOptions['identityToken']
+  private readonly timeoutMs: number
+  private readonly doFetch: typeof globalThis.fetch
+  private readonly retry: Required<RetryOptions>
+  private readonly userAgent: string
+  private readonly onResponse: ClientOptions['onResponse']
+  private readonly sleep: (ms: number) => Promise<void>
+
+  constructor(private readonly options: ClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, '')
+    this.apiKey = options.apiKey
+    this.identityToken = options.identityToken
+    this.timeoutMs = options.timeoutMs ?? 30_000
+    this.doFetch =
+      options.fetch ?? (((input, init) => globalThis.fetch(input, init)) as typeof globalThis.fetch)
+    this.retry = { ...DEFAULT_RETRY, ...options.retry }
+    this.userAgent = [options.userAgent, `ycadence-sdk/${SDK_VERSION}`]
+      .filter((part) => part !== undefined && part !== '')
+      .join(' ')
+    this.onResponse = options.onResponse
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  }
+
+  /** A copy of this client with some options replaced. */
+  withOptions(overrides: Partial<ClientOptions>): YCadenceClient {
+    return new YCadenceClient({ ...this.options, ...overrides })
+  }
+
+  /** The fetch this client sends with; for wrapping in `withOptions`. */
+  get fetchImplementation(): typeof globalThis.fetch {
+    return this.doFetch
+  }
+
+  async health(): Promise<Health> {
+    return this.call('health')
+  }
+
+  /** Who the credential is. A 404 means the server predates Slice 2A. */
+  async me(options?: RequestOptions): Promise<Me> {
+    return this.call('me', {}, undefined, undefined, options)
+  }
+
+  /** Projects the credential can read; `q` matches a name or identifier prefix. */
+  async listProjects(
+    query: { q?: string; archived?: boolean; limit?: number; cursor?: string } = {},
+    options?: RequestOptions
+  ): Promise<Page<Project>> {
+    return this.call('listProjects', {}, query, undefined, options)
+  }
+
+  async listWorkItems(
+    projectId: string,
+    query: ListWorkItemsOptions = {},
+    options?: RequestOptions
+  ): Promise<Page<WorkItem>> {
+    return this.call(
+      'listWorkItems',
+      { projectId },
+      {
+        filter: query.filter === undefined ? undefined : JSON.stringify(query.filter),
+        limit: query.limit,
+        cursor: query.cursor,
+        state: query.state,
+        priority: query.priority,
+      },
+      undefined,
+      options
+    )
+  }
+
+  /**
+   * Every work item matching a filter, following the cursor.
+   *
+   * An async generator rather than an array: a project can hold tens of
+   * thousands of items, and a caller that wanted the first twenty should not
+   * pay for all of them — nor should the process hold them all in memory.
+   */
+  iterateWorkItems(
+    projectId: string,
+    options: { filter?: unknown; pageSize?: number } = {}
+  ): AsyncGenerator<WorkItem> {
+    return paginate((cursor) =>
+      this.listWorkItems(projectId, {
+        filter: options.filter,
+        limit: options.pageSize ?? 100,
+        cursor,
+      })
+    )
+  }
+
+  async createWorkItem(
+    projectId: string,
+    body: CreateWorkItemInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<WorkItem> {
+    return this.call('createWorkItem', { projectId }, undefined, body, options)
+  }
+
+  async getWorkItem(workItemId: string, options?: RequestOptions): Promise<WorkItemDetail> {
+    return this.call('getWorkItem', { workItemId }, undefined, undefined, options)
+  }
+
+  async updateWorkItem(
+    workItemId: string,
+    body: UpdateWorkItemInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<WorkItem> {
+    return this.call('updateWorkItem', { workItemId }, undefined, body, options)
+  }
+
+  async deleteWorkItem(workItemId: string, options?: RequestOptions): Promise<void> {
+    await this.call('deleteWorkItem', { workItemId }, undefined, undefined, options)
+  }
+
+  async listStates(projectId: string, options?: RequestOptions): Promise<{ states: State[] }> {
+    return this.call('listStates', { projectId }, undefined, undefined, options)
+  }
+
+  async listLabels(projectId: string, options?: RequestOptions): Promise<{ labels: Label[] }> {
+    return this.call('listLabels', { projectId }, undefined, undefined, options)
+  }
+
+  async createLabel(
+    projectId: string,
+    body: { name: string; color: string; description?: string },
+    options?: RequestOptions
+  ): Promise<Label> {
+    return this.call('createLabel', { projectId }, undefined, body, options)
+  }
+
+  async listTypes(projectId: string, options?: RequestOptions): Promise<{ types: unknown[] }> {
+    return this.call('listTypes', { projectId }, undefined, undefined, options)
+  }
+
+  async listCycles(projectId: string, options?: RequestOptions): Promise<{ cycles: Cycle[] }> {
+    return this.call('listCycles', { projectId }, undefined, undefined, options)
+  }
+
+  async createCycle(
+    projectId: string,
+    body: { name: string; description?: string; startDate?: string; endDate?: string },
+    options?: RequestOptions
+  ): Promise<Cycle> {
+    return this.call('createCycle', { projectId }, undefined, body, options)
+  }
+
+  async getCycleProgress(cycleId: string, options?: RequestOptions): Promise<CycleProgress> {
+    return this.call('getCycleProgress', { cycleId }, undefined, undefined, options)
+  }
+
+  async addWorkItemsToCycle(
+    cycleId: string,
+    workItemIds: string[],
+    options?: RequestOptions
+  ): Promise<{ added: number }> {
+    return this.call('addWorkItemsToCycle', { cycleId }, undefined, { workItemIds }, options)
+  }
+
+  async listViews(projectId: string, options?: RequestOptions): Promise<{ views: View[] }> {
+    return this.call('listViews', { projectId }, undefined, undefined, options)
+  }
+
+  async createView(
+    projectId: string,
+    body: CreateViewInput,
+    options?: RequestOptions
+  ): Promise<View> {
+    return this.call('createView', { projectId }, undefined, body, options)
+  }
+
+  async listIntake(
+    projectId: string,
+    query: { includeDecided?: boolean } = {},
+    options?: RequestOptions
+  ): Promise<{ items: IntakeItem[] }> {
+    return this.call('listIntake', { projectId }, query, undefined, options)
+  }
+
+  async submitIntake(
+    projectId: string,
+    body: SubmitIntakeInput,
+    options?: RequestOptions
+  ): Promise<SubmitIntakeResult> {
+    return this.call('submitIntake', { projectId }, undefined, body, options)
+  }
+
+  async triageIntake(
+    intakeItemId: string,
+    body: TriageInput,
+    options?: RequestOptions
+  ): Promise<TriageResult> {
+    return this.call('triageIntake', { intakeItemId }, undefined, body, options)
+  }
+
+  async previewImport(
+    projectId: string,
+    body: ImportInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<ImportPreview> {
+    return this.call('previewImport', { projectId }, undefined, body, options)
+  }
+
+  async startImport(
+    projectId: string,
+    body: ImportInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<{ runId: string }> {
+    return this.call('startImport', { projectId }, undefined, body, options)
+  }
+
+  async getImport(runId: string, options?: RequestOptions): Promise<ImportRun> {
+    return this.call('getImport', { runId }, undefined, undefined, options)
+  }
+
+  async listImports(projectId: string, options?: RequestOptions): Promise<{ runs: ImportRun[] }> {
+    return this.call('listImports', { projectId }, undefined, undefined, options)
+  }
+
+  /** Call any operation in the table by id. */
+  async call<T>(
+    operation: OperationId,
+    params: Record<string, string> = {},
+    query?: Record<string, string | number | boolean | undefined>,
+    body?: unknown,
+    options: RequestOptions = {}
+  ): Promise<T> {
+    const { method, path } = OPERATIONS[operation]
+    let url = buildPath(path, params)
+    if (query !== undefined) {
+      const search = new URLSearchParams()
+      for (const [name, value] of Object.entries(query)) {
+        if (value !== undefined) search.set(name, String(value))
+      }
+      const encoded = search.toString()
+      if (encoded.length > 0) url += `?${encoded}`
+    }
+    return this.request<T>(method, url, body, options)
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options: RequestOptions
+  ): Promise<T> {
+    const retryable = isIdempotentMethod(method) || options.idempotencyKey !== undefined
+    const retries = retryable ? (options.retries ?? this.retry.retries) : 0
+
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await this.send<T>(method, path, body, options, attempt)
+      } catch (error) {
+        const failure = error as YCadenceError
+        const again =
+          attempt < retries &&
+          typeof failure.retryable === 'boolean' &&
+          // 409 request_in_progress: the first request with this key is still
+          // running, so asking again later is exactly right.
+          (failure.retryable || failure.code === 'request_in_progress')
+        if (!again) throw error
+        await this.sleep(this.backoff(attempt, failure.retryAfter))
+      }
+    }
+  }
+
+  private backoff(attempt: number, retryAfter: number | undefined): number {
+    if (retryAfter !== undefined) return Math.min(retryAfter * 1000, this.retry.maxDelayMs)
+    const exponential = this.retry.baseDelayMs * 2 ** attempt
+    // Full jitter on the upper half, so a fleet of clients does not retry in step.
+    const jittered = exponential / 2 + Math.random() * (exponential / 2)
+    return Math.min(jittered, this.retry.maxDelayMs)
+  }
+
+  private async send<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options: RequestOptions,
+    attempt: number
+  ): Promise<T> {
+    // An explicit timeout, because the default is none: a hung request holds a
+    // CLI open until the user gives up, and blocks an agent indefinitely.
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs)
+    const abort = () => controller.abort()
+    options.signal?.addEventListener('abort', abort)
+    const started = Date.now()
+
+    let response: Response
+    try {
+      const identityToken =
+        typeof this.identityToken === 'function' ? await this.identityToken() : this.identityToken
+
+      const headers: Record<string, string> = {
+        // Never Authorization for the key: in front of IAP that header must
+        // carry the Google token, and a key there is rejected before the app runs.
+        'x-api-key': this.apiKey,
+        ...(identityToken === undefined || identityToken.length === 0
+          ? {}
+          : { Authorization: `Bearer ${identityToken}` }),
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        Accept: 'application/json',
+        'User-Agent': this.userAgent,
+      }
+      if (options.idempotencyKey !== undefined && !isIdempotentMethod(method)) {
+        headers['Idempotency-Key'] = options.idempotencyKey
+      }
+      if (options.expectedVersion !== undefined && !isIdempotentMethod(method)) {
+        headers['If-Match'] = `"${String(options.expectedVersion).replace(/"/g, '')}"`
+      }
+
+      response = await this.doFetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      })
+    } catch (error) {
+      if (error instanceof RequestIntercepted) throw error
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw createError(
+          408,
+          'timeout',
+          `${method} ${path} timed out after ${this.timeoutMs}ms.`,
+          undefined,
+          { method, path }
+        )
+      }
+      throw createError(
+        0,
+        'network_error',
+        `Could not reach ${this.baseUrl}: ${error instanceof Error ? error.message : 'unknown error'}`,
+        undefined,
+        { method, path }
+      )
+    } finally {
+      clearTimeout(timer)
+      options.signal?.removeEventListener('abort', abort)
+    }
+
+    const headerRequestId = response.headers?.get?.('x-request-id') ?? undefined
+    this.onResponse?.({
+      method,
+      path,
+      status: response.status,
+      requestId: headerRequestId,
+      durationMs: Date.now() - started,
+      attempt,
+      replayed: response.headers?.get?.('idempotent-replayed') === 'true',
+    })
+
+    if (response.status === 204) return undefined as T
+
+    const text = await response.text()
+    const parsed = text.length === 0 ? undefined : safeJson(text)
+
+    if (!response.ok) {
+      const failure = (isRecord(parsed) ? parsed : {}) as Partial<ApiFailure>
+      throw createError(
+        response.status,
+        typeof failure.code === 'string' ? failure.code : codeForStatus(response.status),
+        // The server's message when there is one; the status only as a fallback,
+        // so an unexpected error shape still produces something actionable.
+        typeof failure.error === 'string'
+          ? failure.error
+          : `${method} ${path} failed with ${response.status}.`,
+        failure.issues,
+        {
+          requestId: failure.requestId ?? headerRequestId,
+          details: failure.details,
+          retryAfter: parseRetryAfter(response.headers?.get?.('retry-after') ?? null),
+          method,
+          path,
+        }
+      )
+    }
+
+    return parsed as T
+  }
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function codeForStatus(status: number): string {
+  const codes: Record<number, string> = {
+    400: 'bad_request',
+    401: 'unauthorized',
+    403: 'forbidden',
+    404: 'not_found',
+    409: 'conflict',
+    412: 'precondition_failed',
+    422: 'validation_failed',
+    429: 'rate_limited',
+  }
+  return codes[status] ?? (status >= 500 ? 'server_error' : 'unknown')
+}
+
+/** Seconds, from either form `Retry-After` takes: a number or an HTTP date. */
+export function parseRetryAfter(value: string | null, now = Date.now()): number | undefined {
+  if (value === null || value.trim() === '') return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) return Math.max(0, seconds)
+  const date = Date.parse(value)
+  if (Number.isNaN(date)) return undefined
+  return Math.max(0, Math.ceil((date - now) / 1000))
+}
+
+export type { ImportPreview, ImportRun, Page, WorkItem } from './types'
+
+/**
+ * @deprecated Renamed to {@link YCadenceClient}. This alias stays for one
+ * release so existing integrations keep compiling.
+ */
+export const DevPulseClient = YCadenceClient
+/** @deprecated Renamed to {@link YCadenceClient}. */
+export type DevPulseClient = YCadenceClient
+
+export { type ApiFailure, YCadenceError } from './errors'
+
+/**
+ * @deprecated Renamed to {@link YCadenceError}. The alias is the same class,
+ * so `error instanceof DevPulseError` still matches errors the client throws.
+ */
+export const DevPulseError = YCadenceError
+/** @deprecated Renamed to {@link YCadenceError}. */
+export type DevPulseError = YCadenceError

package/src/errors.ts

@@ -0,0 +1,144 @@
+/**
+ * Errors the client throws.
+ *
+ * One base class, `YCadenceError`, so `instanceof YCadenceError` catches every
+ * failure the client produces, and a subclass per kind of failure, so a caller
+ * can branch on the class instead of comparing status codes. The base keeps its
+ * original positional constructor `(status, code, message, issues)`, because
+ * integrations construct it in their own tests.
+ */
+
+export interface ApiIssue {
+  path: string
+  message: string
+}
+
+/** The error body every v1 route returns (`packages/api/src/types.ts`). */
+export interface ApiFailure {
+  error: string
+  code: string
+  issues?: ApiIssue[]
+  /** Added by the work management contracts; absent on older servers. */
+  details?: Record<string, unknown>
+  requestId?: string
+}
+
+export interface ErrorExtras {
+  /** The server's request id, from the body or the `x-request-id` header. */
+  requestId?: string
+  details?: Record<string, unknown>
+  /** Seconds, from `Retry-After`, when the server sent one. */
+  retryAfter?: number
+  method?: string
+  path?: string
+}
+
+export class YCadenceError extends Error {
+  readonly requestId: string | undefined
+  readonly details: Record<string, unknown> | undefined
+  readonly retryAfter: number | undefined
+  readonly method: string | undefined
+  readonly path: string | undefined
+
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly issues?: ApiIssue[],
+    extras: ErrorExtras = {}
+  ) {
+    super(message)
+    this.name = 'YCadenceError'
+    this.requestId = extras.requestId
+    this.details = extras.details
+    this.retryAfter = extras.retryAfter
+    this.method = extras.method
+    this.path = extras.path
+  }
+
+  /**
+   * Whether retrying unchanged could plausibly succeed: rate limits, server
+   * errors, timeouts and an unreachable host. A 4xx means the request itself
+   * needs to change.
+   */
+  get retryable(): boolean {
+    return this.status === 0 || this.status === 408 || this.status === 429 || this.status >= 500
+  }
+}
+
+/** 400 or 422: the request was understood and refused as invalid. */
+export class YCadenceValidationError extends YCadenceError {
+  override name = 'YCadenceValidationError'
+}
+
+/** 401 or 403: no credential, a bad one, or not allowed. */
+export class YCadencePermissionError extends YCadenceError {
+  override name = 'YCadencePermissionError'
+}
+
+/** 404: missing, deleted, or in another organization. */
+export class YCadenceNotFoundError extends YCadenceError {
+  override name = 'YCadenceNotFoundError'
+}
+
+/** 409: a domain rule, a version conflict, or the same idempotency key still running. */
+export class YCadenceConflictError extends YCadenceError {
+  override name = 'YCadenceConflictError'
+}
+
+/** 412: an `If-Match` precondition failed; reload and try again. */
+export class YCadencePreconditionError extends YCadenceError {
+  override name = 'YCadencePreconditionError'
+}
+
+/** 429: slow down; `retryAfter` says for how long when the server said. */
+export class YCadenceRateLimitError extends YCadenceError {
+  override name = 'YCadenceRateLimitError'
+}
+
+/** Status 0 or 408: the host could not be reached, or did not answer in time. */
+export class YCadenceNetworkError extends YCadenceError {
+  override name = 'YCadenceNetworkError'
+}
+
+/** The class that matches a status. */
+export function errorClassFor(status: number): typeof YCadenceError {
+  if (status === 0 || status === 408) return YCadenceNetworkError
+  if (status === 400 || status === 422) return YCadenceValidationError
+  if (status === 401 || status === 403) return YCadencePermissionError
+  if (status === 404) return YCadenceNotFoundError
+  if (status === 409) return YCadenceConflictError
+  if (status === 412) return YCadencePreconditionError
+  if (status === 429) return YCadenceRateLimitError
+  return YCadenceError
+}
+
+export function createError(
+  status: number,
+  code: string,
+  message: string,
+  issues?: ApiIssue[],
+  extras: ErrorExtras = {}
+): YCadenceError {
+  const ErrorClass = errorClassFor(status)
+  return new ErrorClass(status, code, message, issues, extras)
+}
+
+/**
+ * Thrown, unchanged, through the client by a custom `fetch` that wants to stop
+ * a request without it being reported as a network error. The CLI's
+ * `--dry-run` uses it to show a mutation instead of sending it.
+ */
+export class RequestIntercepted extends Error {
+  override name = 'RequestIntercepted'
+  constructor(
+    readonly request: {
+      method: string
+      url: string
+      headers: Record<string, string>
+      body: unknown
+    }
+  ) {
+    super(`${request.method} ${request.url} was not sent.`)
+  }
+}