@ycadence/sdk 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,37 @@
+export {
+  type ClientOptions,
+  DevPulseClient,
+  DevPulseError,
+  parseRetryAfter,
+  type RequestOptions,
+  type ResponseInfo,
+  type RetryOptions,
+  YCadenceClient,
+} 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'