@ycadence/sdk 0.1.0 → 0.2.0

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.`)
+  }
+}

package/src/index.ts

@@ -1,10 +1,37 @@
 export {
-  type ApiFailure,
   type ClientOptions,
   DevPulseClient,
   DevPulseError,
-  type Page,
-  type WorkItem,
+  parseRetryAfter,
+  type RequestOptions,
+  type ResponseInfo,
+  type RetryOptions,
   YCadenceClient,
-  YCadenceError,
 } from './client.js'
+export {
+  type ApiFailure,
+  type ApiIssue,
+  createError,
+  type ErrorExtras,
+  errorClassFor,
+  RequestIntercepted,
+  YCadenceConflictError,
+  YCadenceError,
+  YCadenceNetworkError,
+  YCadenceNotFoundError,
+  YCadencePermissionError,
+  YCadencePreconditionError,
+  YCadenceRateLimitError,
+  YCadenceValidationError,
+} from './errors.js'
+export {
+  buildPath,
+  type HttpMethod,
+  isIdempotentMethod,
+  OPERATIONS,
+  type Operation,
+  type OperationId,
+} from './operations.js'
+export { collect, paginate } from './pagination.js'
+export * from './types.js'
+export { SDK_VERSION } from './version.js'

package/src/operations.ts

@@ -0,0 +1,74 @@
+/**
+ * Every API operation the client calls, in one table.
+ *
+ * The client builds each request from this table rather than from a path
+ * written inline in a method, so there is one place to compare with the
+ * server: `apps/web/lib/api/sdk-contract.test.ts` fails when an entry has no
+ * matching route contract (unless it is marked `pending`), and the CLI's
+ * reference and `--dry-run` name operations by these ids.
+ */
+
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
+
+export interface Operation {
+  method: HttpMethod
+  /** The route contract's path, with `{param}` placeholders. */
+  path: string
+  /**
+   * Planned by the work management contracts and not served yet. The client
+   * still calls it; a 404 from an older server is reported as such.
+   */
+  pending?: string
+}
+
+export const OPERATIONS = {
+  health: { method: 'GET', path: '/api/health' },
+  me: { method: 'GET', path: '/api/v1/me' },
+  listProjects: { method: 'GET', path: '/api/v1/projects' },
+
+  listWorkItems: { method: 'GET', path: '/api/v1/projects/{projectId}/work-items' },
+  createWorkItem: { method: 'POST', path: '/api/v1/projects/{projectId}/work-items' },
+  getWorkItem: { method: 'GET', path: '/api/v1/work-items/{workItemId}' },
+  updateWorkItem: { method: 'PATCH', path: '/api/v1/work-items/{workItemId}' },
+  deleteWorkItem: { method: 'DELETE', path: '/api/v1/work-items/{workItemId}' },
+
+  listStates: { method: 'GET', path: '/api/v1/projects/{projectId}/states' },
+  listLabels: { method: 'GET', path: '/api/v1/projects/{projectId}/labels' },
+  createLabel: { method: 'POST', path: '/api/v1/projects/{projectId}/labels' },
+  listTypes: { method: 'GET', path: '/api/v1/projects/{projectId}/types' },
+
+  listCycles: { method: 'GET', path: '/api/v1/projects/{projectId}/cycles' },
+  createCycle: { method: 'POST', path: '/api/v1/projects/{projectId}/cycles' },
+  getCycleProgress: { method: 'GET', path: '/api/v1/cycles/{cycleId}/progress' },
+  addWorkItemsToCycle: { method: 'POST', path: '/api/v1/cycles/{cycleId}/work-items' },
+
+  listViews: { method: 'GET', path: '/api/v1/projects/{projectId}/views' },
+  createView: { method: 'POST', path: '/api/v1/projects/{projectId}/views' },
+
+  listIntake: { method: 'GET', path: '/api/v1/projects/{projectId}/intake' },
+  submitIntake: { method: 'POST', path: '/api/v1/projects/{projectId}/intake' },
+  triageIntake: { method: 'POST', path: '/api/v1/intake-items/{intakeItemId}/triage' },
+
+  previewImport: { method: 'POST', path: '/api/v1/projects/{projectId}/imports/preview' },
+  startImport: { method: 'POST', path: '/api/v1/projects/{projectId}/imports' },
+  listImports: { method: 'GET', path: '/api/v1/projects/{projectId}/imports' },
+  getImport: { method: 'GET', path: '/api/v1/imports/{runId}' },
+} as const satisfies Record<string, Operation>
+
+export type OperationId = keyof typeof OPERATIONS
+
+/** GET and HEAD are safe to repeat; anything else needs an idempotency key first. */
+export function isIdempotentMethod(method: string): boolean {
+  return method === 'GET' || method === 'HEAD'
+}
+
+/** Fill `{param}` placeholders, encoding each value. */
+export function buildPath(template: string, params: Record<string, string> = {}): string {
+  return template.replace(/\{(\w+)\}/g, (_match, name: string) => {
+    const value = params[name]
+    if (value === undefined || value === '') {
+      throw new TypeError(`Missing path parameter "${name}" for ${template}.`)
+    }
+    return encodeURIComponent(value)
+  })
+}

package/src/pagination.ts

@@ -0,0 +1,36 @@
+import type { Page } from './types'
+
+/**
+ * Follow `nextCursor` to the end, one page at a time.
+ *
+ * Lazy: a caller that breaks out early pays for the pages it read and no more.
+ */
+export async function* paginate<T>(
+  fetchPage: (cursor: string | undefined) => Promise<Page<T>>,
+  options: { cursor?: string; maxItems?: number } = {}
+): AsyncGenerator<T> {
+  let cursor = options.cursor
+  let yielded = 0
+  do {
+    const page = await fetchPage(cursor)
+    for (const item of page.items) {
+      if (options.maxItems !== undefined && yielded >= options.maxItems) return
+      yielded += 1
+      yield item
+    }
+    cursor = page.nextCursor ?? undefined
+  } while (cursor !== undefined)
+}
+
+/** Every item from {@link paginate}, as an array, up to `maxItems`. */
+export async function collect<T>(
+  iterable: AsyncIterable<T>,
+  maxItems = Number.POSITIVE_INFINITY
+): Promise<T[]> {
+  const items: T[] = []
+  for await (const item of iterable) {
+    if (items.length >= maxItems) break
+    items.push(item)
+  }
+  return items
+}

package/src/types.ts

@@ -0,0 +1,364 @@
+/**
+ * Request and response shapes of the v1 API, as they arrive over JSON.
+ *
+ * The routes define these with zod in `apps/web` (`lib/api/contracts.ts` and
+ * the route files). The SDK is published without dependencies, so it cannot
+ * import those schemas; instead each response type has a field list below that
+ * the compiler checks against the type, and `apps/web/lib/api/sdk-contract.test.ts`
+ * checks against the route's zod schema. A field added on one side and not the
+ * other fails that test rather than reaching a user.
+ *
+ * Dates are ISO strings: that is what JSON carries.
+ */
+
+export type Priority = 'urgent' | 'high' | 'medium' | 'low' | 'none'
+export const PRIORITIES: readonly Priority[] = ['urgent', 'high', 'medium', 'low', 'none']
+
+export type StateGroup = 'backlog' | 'unstarted' | 'started' | 'completed' | 'cancelled' | 'triage'
+
+export interface WorkItem {
+  id: string
+  key: string
+  sequenceId: number
+  name: string
+  priority: Priority
+  stateId: string | null
+  assigneeIds: string[]
+  labelIds: string[]
+  parentId: string | null
+  sortOrder: string
+  createdAt: string
+  /**
+   * Returned by `GET /work-items/{id}` (always, from Slice 2A on); not yet by
+   * lists or writes.
+   */
+  projectId?: string
+  /** Not returned yet. Sent back as `If-Match` once the server versions items. */
+  version?: number
+}
+
+export interface WorkItemDetail extends WorkItem {
+  /** Optional only so the SDK still reads a server older than Slice 2A. */
+  projectId?: string
+  description: string | null
+  startDate: string | null
+  targetDate: string | null
+  archivedAt: string | null
+  updatedAt: string
+}
+
+export interface Page<T> {
+  items: T[]
+  nextCursor: string | null
+}
+
+export interface CreateWorkItemInput {
+  name: string
+  description?: string
+  stateId?: string
+  priority?: Priority
+  assigneeIds?: string[]
+  labelIds?: string[]
+  parentId?: string
+  /** ISO date. */
+  startDate?: string
+  targetDate?: string
+}
+
+/**
+ * The fields PATCH accepts today. The server strips anything else, so sending
+ * an unlisted field would look like success and change nothing.
+ */
+export interface UpdateWorkItemInput {
+  name?: string
+  description?: string
+  stateId?: string
+  priority?: Priority
+  parentId?: string | null
+  startDate?: string | null
+  targetDate?: string | null
+}
+
+export interface ListWorkItemsOptions {
+  /** A @devpulse/query expression; sent JSON-encoded as `filter`. */
+  filter?: unknown
+  limit?: number
+  cursor?: string
+  /** A state id. */
+  state?: string
+  priority?: Priority
+}
+
+export interface State {
+  id: string
+  name: string
+  group: StateGroup | string
+  color: string
+  description: string | null
+  /** Fractional-index sort key; the list arrives already ordered by it. */
+  sequence: string
+  isDefault: boolean
+}
+
+export interface Label {
+  id: string
+  name: string
+  color: string
+  description: string | null
+  sortOrder: string
+}
+
+export interface Cycle {
+  id: string
+  name: string
+  description: string | null
+  startDate: string | null
+  endDate: string | null
+  status: 'draft' | 'upcoming' | 'active' | 'completed'
+  sortOrder: string
+  completedAt: string | null
+  archivedAt: string | null
+}
+
+export interface CycleProgress {
+  progress: unknown
+  burndown: unknown
+  frozen: boolean
+}
+
+export interface View {
+  id: string
+  name: string
+  description: string | null
+  filter: unknown
+  display: unknown
+  access: 'private' | 'public'
+  ownerId: string | null
+  sortOrder: string
+}
+
+export interface CreateViewInput {
+  name: string
+  description?: string
+  where?: unknown
+  display?: Record<string, unknown>
+  access?: 'private' | 'public'
+}
+
+export type IntakeStatus = 'pending' | 'accepted' | 'declined' | 'snoozed' | 'duplicate'
+
+export interface IntakeItem {
+  id: string
+  workItemId: string
+  status: IntakeStatus
+  source: string
+  sourceEmail: string | null
+  snoozedUntil: string | null
+  submittedAt: string
+}
+
+export interface SubmitIntakeInput {
+  title: string
+  description?: string
+  source?: 'in_app' | 'form' | 'email' | 'api' | 'integration'
+  sourceEmail?: string
+  extra?: Record<string, unknown>
+}
+
+export interface SubmitIntakeResult {
+  intakeItemId: string
+  workItemId: string
+  sequenceId: number
+}
+
+export interface TriageInput {
+  status: 'accepted' | 'declined' | 'snoozed' | 'duplicate'
+  /** ISO date; required when snoozing. */
+  snoozedUntil?: string
+  /** Required when marking a duplicate. */
+  duplicateOfId?: string
+}
+
+export interface TriageResult {
+  status: string
+  movedToStateId: string | null
+}
+
+export interface ImportPreview {
+  source: string
+  total: number
+  states: { name: string; suggestedStateId: string | null }[]
+  labels: { name: string; exists: boolean }[]
+  assignees: { value: string; matched: boolean }[]
+  skipped: { row: number; reason: string }[]
+  unmappedPriorities: string[]
+  /**
+   * False when re-importing would create duplicates rather than update — a CSV
+   * with no id column. Worth showing before the import, not after.
+   */
+  idempotent: boolean
+}
+
+export interface ImportRun {
+  id: string
+  source: string
+  status: string
+  totalItems: number
+  createdCount: number
+  updatedCount: number
+  cursor: number
+  skipped: { row: number; reason: string }[]
+  unmatched: { kind: string; value: string; item: string }[]
+  error: string | null
+  startedAt?: string | null
+  finishedAt?: string | null
+  createdAt?: string
+}
+
+export type ImportSource = 'csv' | 'github' | 'jira' | 'linear'
+
+export interface ImportInput {
+  source: ImportSource
+  /** CSV text, or the parsed JSON export for the API sources. */
+  data: unknown
+  repository?: string
+  baseUrl?: string
+  /** Source state name to state id. Only for `startImport`. */
+  stateMap?: Record<string, string>
+}
+
+export interface Health {
+  status: string
+  checks: Record<string, string>
+}
+
+/** `GET /api/v1/me`: who the credential is. Never includes the key. */
+export interface Me {
+  principal: {
+    kind: 'personal_key' | 'service_key' | string
+    scopeType?: 'project' | 'organization' | 'personal' | string
+    apiKeyId: string
+    keyPrefix: string
+    userId: string | null
+    email: string | null
+    organizationRole?: string | null
+  }
+  organization: { id: string; slug: string; name: string }
+  project: { id: string; identifier: string; name: string } | null
+  scopes: string[]
+  expiresAt: string | null
+}
+
+/** `GET /api/v1/projects`. */
+export interface Project {
+  id: string
+  identifier: string
+  name: string
+  archivedAt: string | null
+}
+
+/**
+ * Field lists, checked by the compiler to name every key of the type (and no
+ * others), and by the contract test to match the route's response schema.
+ */
+type FieldsOf<T> = { [K in keyof Required<T>]: true }
+
+export const WORK_ITEM_FIELDS: FieldsOf<WorkItem> = {
+  id: true,
+  key: true,
+  sequenceId: true,
+  name: true,
+  priority: true,
+  stateId: true,
+  assigneeIds: true,
+  labelIds: true,
+  parentId: true,
+  sortOrder: true,
+  createdAt: true,
+  projectId: true,
+  version: true,
+}
+
+export const WORK_ITEM_DETAIL_FIELDS: FieldsOf<WorkItemDetail> = {
+  ...WORK_ITEM_FIELDS,
+  description: true,
+  startDate: true,
+  targetDate: true,
+  archivedAt: true,
+  updatedAt: true,
+}
+
+export const STATE_FIELDS: FieldsOf<State> = {
+  id: true,
+  name: true,
+  group: true,
+  color: true,
+  description: true,
+  sequence: true,
+  isDefault: true,
+}
+
+export const LABEL_FIELDS: FieldsOf<Label> = {
+  id: true,
+  name: true,
+  color: true,
+  description: true,
+  sortOrder: true,
+}
+
+export const CYCLE_FIELDS: FieldsOf<Cycle> = {
+  id: true,
+  name: true,
+  description: true,
+  startDate: true,
+  endDate: true,
+  status: true,
+  sortOrder: true,
+  completedAt: true,
+  archivedAt: true,
+}
+
+export const VIEW_FIELDS: FieldsOf<View> = {
+  id: true,
+  name: true,
+  description: true,
+  filter: true,
+  display: true,
+  access: true,
+  ownerId: true,
+  sortOrder: true,
+}
+
+export const INTAKE_ITEM_FIELDS: FieldsOf<IntakeItem> = {
+  id: true,
+  workItemId: true,
+  status: true,
+  source: true,
+  sourceEmail: true,
+  snoozedUntil: true,
+  submittedAt: true,
+}
+
+export const IMPORT_RUN_FIELDS: FieldsOf<ImportRun> = {
+  id: true,
+  source: true,
+  status: true,
+  totalItems: true,
+  createdCount: true,
+  updatedCount: true,
+  cursor: true,
+  skipped: true,
+  unmatched: true,
+  error: true,
+  startedAt: true,
+  finishedAt: true,
+  createdAt: true,
+}
+
+/**
+ * Fields the SDK declares ahead of the server (the work management contracts
+ * add them). The contract test allows them to be missing from today's schemas.
+ */
+export const PENDING_FIELDS: Record<string, readonly string[]> = {
+  workItem: ['projectId', 'version'],
+}

package/src/version.ts

@@ -0,0 +1,11 @@
+/**
+ * The published version, for `User-Agent`.
+ *
+ * Replaced at build time (`bun build --define`) from package.json, so the
+ * Version PR that bumps package.json needs no second edit. Unbuilt source —
+ * tests, the workspace — reports `0.0.0-dev`.
+ */
+declare const __YCADENCE_SDK_VERSION__: string | undefined
+
+export const SDK_VERSION: string =
+  typeof __YCADENCE_SDK_VERSION__ === 'string' ? __YCADENCE_SDK_VERSION__ : '0.0.0-dev'