@canopy-io/node 0.1.0

package/dist/index.cjs

@@ -0,0 +1,625 @@
+'use strict';
+
+// src/errors.ts
+var CanopyError = class extends Error {
+  name = "CanopyError";
+  statusCode;
+  code;
+  details;
+  data;
+  /** The path and method that failed, for logging. */
+  request;
+  constructor(body, request) {
+    super(body.message);
+    this.statusCode = body.statusCode;
+    this.code = body.code;
+    this.details = body.details;
+    this.data = body.data;
+    this.request = request;
+  }
+  /** A 429. `retryAfterMs` is populated when the server said how long to wait. */
+  get isRateLimited() {
+    return this.statusCode === 429;
+  }
+  /** 401 or 403 — the credential is wrong or not permitted here. */
+  get isAuthFailure() {
+    return this.statusCode === 401 || this.statusCode === 403;
+  }
+};
+var CanopyConnectionError = class extends Error {
+  name = "CanopyConnectionError";
+  request;
+  constructor(message, request, options) {
+    super(message, options);
+    this.request = request;
+  }
+};
+function isCanopyError(error) {
+  return error instanceof Error && error.name === "CanopyError";
+}
+function isCanopyConnectionError(error) {
+  return error instanceof Error && error.name === "CanopyConnectionError";
+}
+
+// src/client.ts
+function isCursorPagination(pagination) {
+  return "next_cursor" in pagination;
+}
+var DEFAULT_BASE_URL = "https://auth.canopy-io.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE"]);
+var CanopyClient = class {
+  baseUrl;
+  timeoutMs;
+  maxRetries;
+  authHeaders;
+  extraHeaders;
+  fetchImpl;
+  constructor(options = {}) {
+    if (!options.apiKey && !options.accessToken) {
+      throw new TypeError(
+        "CanopyClient requires either `apiKey` (server-to-server) or `accessToken` (a user or identity JWT)."
+      );
+    }
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.extraHeaders = options.headers ?? {};
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") {
+      throw new TypeError(
+        "No `fetch` available. Node 18+ provides one; on older runtimes pass `fetch` explicitly."
+      );
+    }
+    this.authHeaders = options.apiKey ? { "X-API-Key": options.apiKey } : { Authorization: `Bearer ${options.accessToken ?? ""}` };
+  }
+  /**
+   * Issue a request and return the payload with the envelope removed.
+   *
+   *   `{ data }`               → the resource
+   *   `{ items, pagination }`  → the whole object, so pagination survives
+   *   `{ summary, results }`   → the whole object
+   *   204                      → undefined
+   *
+   * Non-2xx throws `CanopyError`; a request that never completed throws
+   * `CanopyConnectionError`.
+   */
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const upper = method.toUpperCase();
+    const retryable = options.idempotent ?? IDEMPOTENT_METHODS.has(upper);
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        await delay(backoffMs(attempt, lastError));
+      }
+      try {
+        const response = await this.send(upper, url, options);
+        if (this.shouldRetry(response.status, retryable, attempt)) {
+          lastError = await this.toError(response, upper, path);
+          continue;
+        }
+        if (!response.ok) {
+          throw await this.toError(response, upper, path);
+        }
+        return await this.unwrap(response);
+      } catch (error) {
+        if (error instanceof CanopyError) {
+          throw error;
+        }
+        lastError = error;
+        if (!retryable || attempt === this.maxRetries) {
+          throw new CanopyConnectionError(
+            `${upper} ${path} failed: ${describe(error)}`,
+            { method: upper, path },
+            { cause: error }
+          );
+        }
+      }
+    }
+    throw new CanopyConnectionError(
+      `${upper} ${path} exhausted ${this.maxRetries + 1} attempts`,
+      { method: upper, path },
+      { cause: lastError }
+    );
+  }
+  shouldRetry(status, retryable, attempt) {
+    if (attempt >= this.maxRetries) {
+      return false;
+    }
+    if (status === 429) {
+      return true;
+    }
+    return status >= 500 && retryable;
+  }
+  async send(method, url, options) {
+    const controller = new AbortController();
+    const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : void 0;
+    const onAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const headers = {
+      Accept: "application/json",
+      ...this.extraHeaders,
+      ...this.authHeaders
+    };
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const init = { method, headers, signal: controller.signal };
+    if (options.body !== void 0) {
+      init.body = JSON.stringify(options.body);
+    }
+    try {
+      return await this.fetchImpl(url, init);
+    } finally {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  buildUrl(path, query) {
+    const url = new URL(
+      path.startsWith("/") ? path : `/${path}`,
+      `${this.baseUrl}/`
+    );
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value === void 0 || value === null) {
+        continue;
+      }
+      url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async unwrap(response) {
+    if (response.status === 204) {
+      return void 0;
+    }
+    const text = await response.text();
+    if (text === "") {
+      return void 0;
+    }
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && "data" in parsed) {
+      return parsed["data"];
+    }
+    return parsed;
+  }
+  async toError(response, method, path) {
+    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+    let body = {
+      statusCode: response.status,
+      code: null,
+      message: `${response.status} ${response.statusText}`.trim()
+    };
+    try {
+      const parsed = JSON.parse(await response.text());
+      if (parsed.error) {
+        body = {
+          ...parsed.error,
+          statusCode: parsed.error.statusCode ?? response.status
+        };
+      }
+    } catch {
+    }
+    const error = new CanopyError(body, { method, path });
+    if (retryAfter !== null) {
+      Object.defineProperty(error, "retryAfterMs", {
+        value: retryAfter,
+        enumerable: true
+      });
+    }
+    return error;
+  }
+};
+function parseRetryAfter(header) {
+  if (!header) {
+    return null;
+  }
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) {
+    return Math.max(0, seconds * 1e3);
+  }
+  const date = Date.parse(header);
+  if (Number.isNaN(date)) {
+    return null;
+  }
+  return Math.max(0, date - Date.now());
+}
+function backoffMs(attempt, lastError) {
+  const advised = lastError && typeof lastError === "object" && "retryAfterMs" in lastError ? Number(lastError.retryAfterMs) : NaN;
+  if (Number.isFinite(advised)) {
+    return advised;
+  }
+  const base = 250 * 2 ** (attempt - 1);
+  return base + Math.random() * base;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describe(error) {
+  if (error instanceof Error) {
+    return error.name === "AbortError" ? "timed out or aborted" : error.message;
+  }
+  return String(error);
+}
+
+// src/pagination.ts
+var DEFAULT_MAX_PAGES = 1e3;
+var Paginator = class {
+  fetchPage;
+  initial;
+  maxPages;
+  constructor(fetchPage, initial = {}, options = {}) {
+    this.fetchPage = fetchPage;
+    this.initial = initial;
+    this.maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+  }
+  /** Every item across every page. */
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.pages()) {
+      for (const item of page.items) {
+        yield item;
+      }
+    }
+  }
+  /**
+   * Page by page, for callers that need the pagination metadata or want to
+   * process in batches rather than item by item.
+   */
+  async *pages() {
+    let params = { ...this.initial };
+    let seenCursor = null;
+    let pageCount = 0;
+    for (; ; ) {
+      const page = await this.fetchPage(params);
+      pageCount++;
+      yield page;
+      const pagination = page.pagination;
+      if (!pagination) {
+        return;
+      }
+      if (page.items.length === 0) {
+        return;
+      }
+      if (pageCount >= this.maxPages) {
+        return;
+      }
+      if (isCursorPagination(pagination)) {
+        const next = pagination.next_cursor;
+        if (next === null || next === seenCursor) {
+          return;
+        }
+        seenCursor = next;
+        params = { ...params, cursor: next };
+        continue;
+      }
+      if (!pagination.has_next_page) {
+        return;
+      }
+      params = { ...params, page: pagination.page + 1 };
+    }
+  }
+  /**
+   * Collect everything into an array.
+   *
+   * Bounded on purpose: an unbounded drain of an audit log will exhaust memory
+   * on a busy account, so the cap is a parameter rather than a footnote. Use
+   * the iterator for large feeds.
+   */
+  async all(max = 1e4) {
+    const collected = [];
+    for await (const item of this) {
+      collected.push(item);
+      if (collected.length >= max) {
+        break;
+      }
+    }
+    return collected;
+  }
+  /** The first item, or undefined. Stops after one page. */
+  async first() {
+    for await (const item of this) {
+      return item;
+    }
+    return void 0;
+  }
+};
+function paginate(fetchPage, initial = {}, options = {}) {
+  return new Paginator(fetchPage, initial, options);
+}
+
+// src/resources/assignments.ts
+var Assignments = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Every assignment in the Application, across all nodes. */
+  list(query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", "/api/v1/assignments/app-wide", {
+        query: params
+      }),
+      { ...query }
+    );
+  }
+  /**
+   * Grant a role at a node.
+   *
+   * Not retried automatically on a 5xx: a repeat could create a second grant,
+   * and the server cannot tell the two apart. If the call fails without an
+   * answer, read the current assignments before retrying.
+   */
+  create(input) {
+    return this.client.request("POST", "/api/v1/assignments", { body: input });
+  }
+  update(id, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/v1/assignments/${encodeURIComponent(id)}`,
+      { body: input }
+    );
+  }
+  delete(id) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/assignments/${encodeURIComponent(id)}`
+    );
+  }
+  /**
+   * Grant many at once. Answers 207 with a per-item result rather than failing
+   * the batch, so inspect `results` — a 2xx here does not mean every grant
+   * succeeded.
+   */
+  bulkCreate(input) {
+    return this.client.request("POST", "/api/v1/assignments/bulk-create", {
+      body: input
+    });
+  }
+  /** Same partial-success contract as `bulkCreate`. */
+  bulkRemove(input) {
+    return this.client.request("POST", "/api/v1/assignments/bulk-remove", {
+      body: input
+    });
+  }
+  /** Same partial-success contract as `bulkCreate`. */
+  bulkChangeRole(input) {
+    return this.client.request("POST", "/api/v1/assignments/bulk-change-role", {
+      body: input
+    });
+  }
+};
+
+// src/resources/identities.ts
+var Identities = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", "/api/v1/identities", { query: params }),
+      { ...query }
+    );
+  }
+  get(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/identities/${encodeURIComponent(id)}`
+    );
+  }
+  create(input) {
+    return this.client.request("POST", "/api/v1/identities", { body: input });
+  }
+  update(id, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/v1/identities/${encodeURIComponent(id)}`,
+      { body: input }
+    );
+  }
+  delete(id) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/identities/${encodeURIComponent(id)}`
+    );
+  }
+  /**
+   * Deactivation is the reversible counterpart to `delete` — sessions are
+   * revoked and sign-in refused, but the identity and its assignments survive.
+   * Prefer it for offboarding you may need to undo.
+   */
+  deactivate(id) {
+    return this.client.request(
+      "POST",
+      `/api/v1/identities/${encodeURIComponent(id)}/deactivate`
+    );
+  }
+  activate(id) {
+    return this.client.request(
+      "POST",
+      `/api/v1/identities/${encodeURIComponent(id)}/activate`
+    );
+  }
+  /** Every role this identity holds, and where. */
+  assignments(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/identities/${encodeURIComponent(id)}/assignments`
+    );
+  }
+  /**
+   * The permissions this identity effectively holds, inheritance resolved.
+   *
+   * For enforcing a single check, use `permissions.evaluate` — it answers one
+   * question at the node that matters. This is for showing a person what
+   * someone can do.
+   */
+  permissions(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/identities/${encodeURIComponent(id)}/permissions`
+    );
+  }
+};
+
+// src/resources/permissions.ts
+var Permissions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Ask whether an identity holds a permission.
+   *
+   * With `scope: "node"` the engine walks the node's lineage, so a permission
+   * granted on an ancestor is inherited at `node_id`. With `scope: "app_wide"`
+   * it answers the coarse "anywhere in this Application" question and returns
+   * `effective_node_id: null` — that answer must never be used to guard a
+   * resource that belongs to a specific node, which is why the scope is a
+   * required field rather than a default.
+   */
+  evaluate(input) {
+    return this.client.request("POST", "/api/v1/permissions/evaluate", {
+      body: input
+    });
+  }
+  /**
+   * Evaluate many decisions in one round trip.
+   *
+   * Prefer this to a loop over `evaluate` when rendering a screen: the checks
+   * are answered together instead of paying request latency for each.
+   */
+  evaluateBulk(input) {
+    return this.client.request("POST", "/api/v1/permissions/evaluate/bulk", {
+      body: input
+    });
+  }
+  /**
+   * The same decision with its reasoning — which role granted it, which node
+   * it was inherited from. For debugging an unexpected allow or deny, not for
+   * the enforcement path.
+   */
+  explain(input) {
+    return this.client.request("POST", "/api/v1/permissions/evaluate/explain", {
+      body: input
+    });
+  }
+  /** Every permission in the Environment, page by page. */
+  list(query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", "/api/v1/permissions", { query: params }),
+      { ...query }
+    );
+  }
+  get(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/permissions/${encodeURIComponent(id)}`
+    );
+  }
+  /** Define permissions. The request takes a batch, not a single key. */
+  create(input) {
+    return this.client.request("POST", "/api/v1/permissions", { body: input });
+  }
+  update(id, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/v1/permissions/${encodeURIComponent(id)}`,
+      { body: input }
+    );
+  }
+  delete(id) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/permissions/${encodeURIComponent(id)}`
+    );
+  }
+};
+
+// src/resources/roles.ts
+var Roles = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", "/api/v1/roles", { query: params }),
+      { ...query }
+    );
+  }
+  get(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/roles/${encodeURIComponent(id)}`
+    );
+  }
+  create(input) {
+    return this.client.request("POST", "/api/v1/roles", { body: input });
+  }
+  update(id, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/v1/roles/${encodeURIComponent(id)}`,
+      { body: input }
+    );
+  }
+  delete(id) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/roles/${encodeURIComponent(id)}`
+    );
+  }
+  permissions(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/roles/${encodeURIComponent(id)}/permissions`
+    );
+  }
+  /**
+   * Replaces the role's permissions wholesale — this is a PUT, so anything
+   * absent from `input` is removed. Read `permissions` first if you mean to add.
+   */
+  setPermissions(id, input) {
+    return this.client.request(
+      "PUT",
+      `/api/v1/roles/${encodeURIComponent(id)}/permissions`,
+      { body: input }
+    );
+  }
+};
+
+// src/canopy.ts
+var Canopy = class {
+  client;
+  permissions;
+  identities;
+  roles;
+  assignments;
+  constructor(options) {
+    this.client = new CanopyClient(options);
+    this.permissions = new Permissions(this.client);
+    this.identities = new Identities(this.client);
+    this.roles = new Roles(this.client);
+    this.assignments = new Assignments(this.client);
+  }
+};
+
+exports.Assignments = Assignments;
+exports.Canopy = Canopy;
+exports.CanopyClient = CanopyClient;
+exports.CanopyConnectionError = CanopyConnectionError;
+exports.CanopyError = CanopyError;
+exports.Identities = Identities;
+exports.Paginator = Paginator;
+exports.Permissions = Permissions;
+exports.Roles = Roles;
+exports.isCanopyConnectionError = isCanopyConnectionError;
+exports.isCanopyError = isCanopyError;
+exports.isCursorPagination = isCursorPagination;
+exports.paginate = paginate;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map