@ycadence/sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,126 +1,376 @@
-// src/client.ts
+// src/errors.ts
 class YCadenceError extends Error {
   status;
   code;
   issues;
-  constructor(status, code, message, issues) {
+  requestId;
+  details;
+  retryAfter;
+  method;
+  path;
+  constructor(status, code, message, issues, extras = {}) {
     super(message);
     this.status = status;
     this.code = code;
     this.issues = issues;
     this.name = "YCadenceError";
+    this.requestId = extras.requestId;
+    this.details = extras.details;
+    this.retryAfter = extras.retryAfter;
+    this.method = extras.method;
+    this.path = extras.path;
   }
   get retryable() {
-    return this.status === 429 || this.status >= 500;
+    return this.status === 0 || this.status === 408 || this.status === 429 || this.status >= 500;
   }
 }
 
+class YCadenceValidationError extends YCadenceError {
+  name = "YCadenceValidationError";
+}
+
+class YCadencePermissionError extends YCadenceError {
+  name = "YCadencePermissionError";
+}
+
+class YCadenceNotFoundError extends YCadenceError {
+  name = "YCadenceNotFoundError";
+}
+
+class YCadenceConflictError extends YCadenceError {
+  name = "YCadenceConflictError";
+}
+
+class YCadencePreconditionError extends YCadenceError {
+  name = "YCadencePreconditionError";
+}
+
+class YCadenceRateLimitError extends YCadenceError {
+  name = "YCadenceRateLimitError";
+}
+
+class YCadenceNetworkError extends YCadenceError {
+  name = "YCadenceNetworkError";
+}
+function errorClassFor(status) {
+  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;
+}
+function createError(status, code, message, issues, extras = {}) {
+  const ErrorClass = errorClassFor(status);
+  return new ErrorClass(status, code, message, issues, extras);
+}
+
+class RequestIntercepted extends Error {
+  request;
+  name = "RequestIntercepted";
+  constructor(request) {
+    super(`${request.method} ${request.url} was not sent.`);
+    this.request = request;
+  }
+}
+
+// src/operations.ts
+var 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}" }
+};
+function isIdempotentMethod(method) {
+  return method === "GET" || method === "HEAD";
+}
+function buildPath(template, params = {}) {
+  return template.replace(/\{(\w+)\}/g, (_match, name) => {
+    const value = params[name];
+    if (value === undefined || value === "") {
+      throw new TypeError(`Missing path parameter "${name}" for ${template}.`);
+    }
+    return encodeURIComponent(value);
+  });
+}
+
+// src/pagination.ts
+async function* paginate(fetchPage, options = {}) {
+  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);
+}
+async function collect(iterable, maxItems = Number.POSITIVE_INFINITY) {
+  const items = [];
+  for await (const item of iterable) {
+    if (items.length >= maxItems)
+      break;
+    items.push(item);
+  }
+  return items;
+}
+
+// src/version.ts
+var SDK_VERSION = "0.2.0";
+
+// src/client.ts
+var DEFAULT_RETRY = { retries: 2, baseDelayMs: 250, maxDelayMs: 8000 };
+
 class YCadenceClient {
+  options;
   baseUrl;
   apiKey;
   identityToken;
   timeoutMs;
   doFetch;
+  retry;
+  userAgent;
+  onResponse;
+  sleep;
   constructor(options) {
+    this.options = options;
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
     this.apiKey = options.apiKey;
     this.identityToken = options.identityToken;
     this.timeoutMs = options.timeoutMs ?? 30000;
-    this.doFetch = options.fetch ?? globalThis.fetch;
+    this.doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    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)));
+  }
+  withOptions(overrides) {
+    return new YCadenceClient({ ...this.options, ...overrides });
+  }
+  get fetchImplementation() {
+    return this.doFetch;
   }
   async health() {
-    return this.request("GET", "/api/health");
-  }
-  async listWorkItems(projectId, options = {}) {
-    const query = new URLSearchParams;
-    if (options.filter !== undefined)
-      query.set("filter", JSON.stringify(options.filter));
-    if (options.limit !== undefined)
-      query.set("limit", String(options.limit));
-    if (options.cursor !== undefined)
-      query.set("cursor", options.cursor);
-    return this.request("GET", `/api/v1/projects/${projectId}/work-items?${query}`);
-  }
-  async* iterateWorkItems(projectId, options = {}) {
-    let cursor;
-    do {
-      const page = await this.listWorkItems(projectId, {
-        filter: options.filter,
-        limit: options.pageSize ?? 100,
-        cursor
-      });
-      for (const item of page.items)
-        yield item;
-      cursor = page.nextCursor ?? undefined;
-    } while (cursor !== undefined);
+    return this.call("health");
+  }
+  async me(options) {
+    return this.call("me", {}, undefined, undefined, options);
   }
-  async createWorkItem(projectId, body) {
-    return this.request("POST", `/api/v1/projects/${projectId}/work-items`, body);
+  async listProjects(query = {}, options) {
+    return this.call("listProjects", {}, query, undefined, options);
   }
-  async getWorkItem(workItemId) {
-    return this.request("GET", `/api/v1/work-items/${workItemId}`);
+  async listWorkItems(projectId, query = {}, options) {
+    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);
   }
-  async updateWorkItem(workItemId, body) {
-    return this.request("PATCH", `/api/v1/work-items/${workItemId}`, body);
+  iterateWorkItems(projectId, options = {}) {
+    return paginate((cursor) => this.listWorkItems(projectId, {
+      filter: options.filter,
+      limit: options.pageSize ?? 100,
+      cursor
+    }));
   }
-  async deleteWorkItem(workItemId) {
-    await this.request("DELETE", `/api/v1/work-items/${workItemId}`);
+  async createWorkItem(projectId, body, options) {
+    return this.call("createWorkItem", { projectId }, undefined, body, options);
   }
-  async listStates(projectId) {
-    return this.request("GET", `/api/v1/projects/${projectId}/states`);
+  async getWorkItem(workItemId, options) {
+    return this.call("getWorkItem", { workItemId }, undefined, undefined, options);
   }
-  async listLabels(projectId) {
-    return this.request("GET", `/api/v1/projects/${projectId}/labels`);
+  async updateWorkItem(workItemId, body, options) {
+    return this.call("updateWorkItem", { workItemId }, undefined, body, options);
   }
-  async listCycles(projectId) {
-    return this.request("GET", `/api/v1/projects/${projectId}/cycles`);
+  async deleteWorkItem(workItemId, options) {
+    await this.call("deleteWorkItem", { workItemId }, undefined, undefined, options);
   }
-  async previewImport(projectId, body) {
-    return this.request("POST", `/api/v1/projects/${projectId}/imports/preview`, body);
+  async listStates(projectId, options) {
+    return this.call("listStates", { projectId }, undefined, undefined, options);
   }
-  async startImport(projectId, body) {
-    return this.request("POST", `/api/v1/projects/${projectId}/imports`, body);
+  async listLabels(projectId, options) {
+    return this.call("listLabels", { projectId }, undefined, undefined, options);
   }
-  async getImport(runId) {
-    return this.request("GET", `/api/v1/imports/${runId}`);
+  async createLabel(projectId, body, options) {
+    return this.call("createLabel", { projectId }, undefined, body, options);
   }
-  async listImports(projectId) {
-    return this.request("GET", `/api/v1/projects/${projectId}/imports`);
+  async listTypes(projectId, options) {
+    return this.call("listTypes", { projectId }, undefined, undefined, options);
   }
-  async listViews(projectId) {
-    return this.request("GET", `/api/v1/projects/${projectId}/views`);
+  async listCycles(projectId, options) {
+    return this.call("listCycles", { projectId }, undefined, undefined, options);
   }
-  async request(method, path, body) {
+  async createCycle(projectId, body, options) {
+    return this.call("createCycle", { projectId }, undefined, body, options);
+  }
+  async getCycleProgress(cycleId, options) {
+    return this.call("getCycleProgress", { cycleId }, undefined, undefined, options);
+  }
+  async addWorkItemsToCycle(cycleId, workItemIds, options) {
+    return this.call("addWorkItemsToCycle", { cycleId }, undefined, { workItemIds }, options);
+  }
+  async listViews(projectId, options) {
+    return this.call("listViews", { projectId }, undefined, undefined, options);
+  }
+  async createView(projectId, body, options) {
+    return this.call("createView", { projectId }, undefined, body, options);
+  }
+  async listIntake(projectId, query = {}, options) {
+    return this.call("listIntake", { projectId }, query, undefined, options);
+  }
+  async submitIntake(projectId, body, options) {
+    return this.call("submitIntake", { projectId }, undefined, body, options);
+  }
+  async triageIntake(intakeItemId, body, options) {
+    return this.call("triageIntake", { intakeItemId }, undefined, body, options);
+  }
+  async previewImport(projectId, body, options) {
+    return this.call("previewImport", { projectId }, undefined, body, options);
+  }
+  async startImport(projectId, body, options) {
+    return this.call("startImport", { projectId }, undefined, body, options);
+  }
+  async getImport(runId, options) {
+    return this.call("getImport", { runId }, undefined, undefined, options);
+  }
+  async listImports(projectId, options) {
+    return this.call("listImports", { projectId }, undefined, undefined, options);
+  }
+  async call(operation, params = {}, query, body, options = {}) {
+    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(method, url, body, options);
+  }
+  async request(method, path, body, options) {
+    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(method, path, body, options, attempt);
+      } catch (error) {
+        const failure = error;
+        const again = attempt < retries && typeof failure.retryable === "boolean" && (failure.retryable || failure.code === "request_in_progress");
+        if (!again)
+          throw error;
+        await this.sleep(this.backoff(attempt, failure.retryAfter));
+      }
+    }
+  }
+  backoff(attempt, retryAfter) {
+    if (retryAfter !== undefined)
+      return Math.min(retryAfter * 1000, this.retry.maxDelayMs);
+    const exponential = this.retry.baseDelayMs * 2 ** attempt;
+    const jittered = exponential / 2 + Math.random() * (exponential / 2);
+    return Math.min(jittered, this.retry.maxDelayMs);
+  }
+  async send(method, path, body, options, attempt) {
     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;
     try {
       const identityToken = typeof this.identityToken === "function" ? await this.identityToken() : this.identityToken;
+      const headers = {
+        "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: {
-          "x-api-key": this.apiKey,
-          ...identityToken === undefined || identityToken.length === 0 ? {} : { Authorization: `Bearer ${identityToken}` },
-          ...body === undefined ? {} : { "Content-Type": "application/json" }
-        },
+        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 new YCadenceError(408, "timeout", `${method} ${path} timed out after ${this.timeoutMs}ms.`);
+        throw createError(408, "timeout", `${method} ${path} timed out after ${this.timeoutMs}ms.`, undefined, { method, path });
       }
-      throw new YCadenceError(0, "network_error", `Could not reach ${this.baseUrl}: ${error instanceof Error ? error.message : "unknown error"}`);
+      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;
     const text = await response.text();
     const parsed = text.length === 0 ? undefined : safeJson(text);
     if (!response.ok) {
-      const failure = parsed ?? {};
-      throw new YCadenceError(response.status, failure.code ?? "unknown", failure.error ?? `${method} ${path} failed with ${response.status}.`, failure.issues);
+      const failure = isRecord(parsed) ? parsed : {};
+      throw createError(response.status, typeof failure.code === "string" ? failure.code : codeForStatus(response.status), 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;
   }
@@ -132,14 +382,157 @@ function safeJson(text) {
     return;
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function codeForStatus(status) {
+  const codes = {
+    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");
+}
+function parseRetryAfter(value, now = Date.now()) {
+  if (value === null || value.trim() === "")
+    return;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds))
+    return Math.max(0, seconds);
+  const date = Date.parse(value);
+  if (Number.isNaN(date))
+    return;
+  return Math.max(0, Math.ceil((date - now) / 1000));
+}
 var DevPulseClient = YCadenceClient;
 var DevPulseError = YCadenceError;
+// src/types.ts
+var PRIORITIES = ["urgent", "high", "medium", "low", "none"];
+var WORK_ITEM_FIELDS = {
+  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
+};
+var WORK_ITEM_DETAIL_FIELDS = {
+  ...WORK_ITEM_FIELDS,
+  description: true,
+  startDate: true,
+  targetDate: true,
+  archivedAt: true,
+  updatedAt: true
+};
+var STATE_FIELDS = {
+  id: true,
+  name: true,
+  group: true,
+  color: true,
+  description: true,
+  sequence: true,
+  isDefault: true
+};
+var LABEL_FIELDS = {
+  id: true,
+  name: true,
+  color: true,
+  description: true,
+  sortOrder: true
+};
+var CYCLE_FIELDS = {
+  id: true,
+  name: true,
+  description: true,
+  startDate: true,
+  endDate: true,
+  status: true,
+  sortOrder: true,
+  completedAt: true,
+  archivedAt: true
+};
+var VIEW_FIELDS = {
+  id: true,
+  name: true,
+  description: true,
+  filter: true,
+  display: true,
+  access: true,
+  ownerId: true,
+  sortOrder: true
+};
+var INTAKE_ITEM_FIELDS = {
+  id: true,
+  workItemId: true,
+  status: true,
+  source: true,
+  sourceEmail: true,
+  snoozedUntil: true,
+  submittedAt: true
+};
+var IMPORT_RUN_FIELDS = {
+  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
+};
+var PENDING_FIELDS = {
+  workItem: ["projectId", "version"]
+};
 export {
+  CYCLE_FIELDS,
   DevPulseClient,
   DevPulseError,
+  IMPORT_RUN_FIELDS,
+  INTAKE_ITEM_FIELDS,
+  LABEL_FIELDS,
+  OPERATIONS,
+  PENDING_FIELDS,
+  PRIORITIES,
+  RequestIntercepted,
+  SDK_VERSION,
+  STATE_FIELDS,
+  VIEW_FIELDS,
+  WORK_ITEM_DETAIL_FIELDS,
+  WORK_ITEM_FIELDS,
   YCadenceClient,
-  YCadenceError
+  YCadenceConflictError,
+  YCadenceError,
+  YCadenceNetworkError,
+  YCadenceNotFoundError,
+  YCadencePermissionError,
+  YCadencePreconditionError,
+  YCadenceRateLimitError,
+  YCadenceValidationError,
+  buildPath,
+  collect,
+  createError,
+  errorClassFor,
+  isIdempotentMethod,
+  paginate,
+  parseRetryAfter
 };
 
-//# debugId=A00F26E6EB147FF564756E2164756E21
+//# debugId=C4191F8D9028EF8064756E2164756E21
 //# sourceMappingURL=index.js.map