cograph 0.1.24 → 0.1.27

package/dist/index.js

@@ -116,12 +116,23 @@ var Client = class {
   apiKey;
   baseUrl;
   tenant;
+  /**
+   * Raw / passthrough API — one method per canonical backend operation, with
+   * the path encoded inside the SDK. Each method returns the backend
+   * {@link Response} VERBATIM: it does NOT throw on non-2xx and does NOT reshape
+   * the body. This is the seam the webapp's proxy layer adopts so per-operation
+   * paths live in one place (here) instead of being hand-rolled at each call
+   * site. See {@link RawApi}. The typed methods on this class (which throw on
+   * non-2xx and reshape some payloads) are left unchanged — this is additive.
+   */
+  raw;
   constructor(opts = {}) {
     const cfg = readConfig();
     this.apiKey = opts.apiKey ?? envVar("API_KEY") ?? cfg.apiKey;
     const url = opts.baseUrl ?? envVar("API_URL") ?? cfg.apiUrl ?? "https://api.cograph.cloud";
     this.baseUrl = url.replace(/\/+$/, "");
     this.tenant = opts.tenant ?? envVar("TENANT") ?? cfg.tenant ?? "demo-tenant";
+    this.raw = new RawApi(this);
   }
   headers() {
     const h = { "Content-Type": "application/json" };
@@ -131,6 +142,158 @@ var Client = class {
   base() {
     return `${this.baseUrl}/graphs/${this.tenant}`;
   }
+  // --- Path builders -------------------------------------------------------- #
+  // SINGLE source of truth for every canonical backend path. Both the raw API
+  // and the new typed parsed methods build URLs through these, so a path lives
+  // in exactly one place. Tenant-scoped paths hang off `base()`
+  // (`{baseUrl}/graphs/{tenant}`); the handful of account-level paths
+  // (e.g. tenant CRUD) hang off `baseUrl` directly.
+  //
+  // These are marked `@internal` (not part of the public SDK surface) but are
+  // not `private`, so the sibling {@link RawApi} can build the same canonical
+  // paths without duplicating them.
+  /** @internal */
+  pAgent() {
+    return `${this.base()}/agent`;
+  }
+  /** @internal */
+  pAsk() {
+    return `${this.base()}/ask`;
+  }
+  /** @internal */
+  pIngest() {
+    return `${this.base()}/ingest`;
+  }
+  /** @internal */
+  pIngestCsvSchema() {
+    return `${this.base()}/ingest/csv/schema`;
+  }
+  /** @internal */
+  pIngestCsvRows() {
+    return `${this.base()}/ingest/csv/rows`;
+  }
+  /** @internal */
+  pEnrichJobs() {
+    return `${this.base()}/enrich/jobs`;
+  }
+  /** @internal */
+  pEnrichJob(jobId) {
+    return `${this.base()}/enrich/jobs/${encodeURIComponent(jobId)}`;
+  }
+  /** @internal */
+  pEnrichJobConflicts(jobId) {
+    return `${this.pEnrichJob(jobId)}/conflicts`;
+  }
+  /** @internal */
+  pEnrichJobApply(jobId) {
+    return `${this.pEnrichJob(jobId)}/apply`;
+  }
+  /** @internal */
+  pOntologyTypes() {
+    return `${this.base()}/ontology/types`;
+  }
+  /** @internal */
+  pOntologyResolve() {
+    return `${this.base()}/ontology/resolve`;
+  }
+  /** @internal Targets the premium ontology-recommender route, mounted only on
+   *  deployments with the proprietary layer — 404s on bare OSS. */
+  pOntologyRecommend() {
+    return `${this.base()}/ontology/recommend`;
+  }
+  /** @internal */
+  pOntologyApply() {
+    return `${this.base()}/ontology/apply`;
+  }
+  /** @internal */
+  pKgs() {
+    return `${this.base()}/kgs`;
+  }
+  /** @internal */
+  pKg(name) {
+    return `${this.base()}/kgs/${encodeURIComponent(name)}`;
+  }
+  /** @internal */
+  pTypeCounts(kg) {
+    return `${this.pKg(kg)}/type-counts`;
+  }
+  /** @internal */
+  pExploreSummary(kg, typeName) {
+    return `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/types/${encodeURIComponent(typeName)}/summary`;
+  }
+  /** @internal */
+  pExploreRecords(kg, typeName, query) {
+    return `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/types/${encodeURIComponent(typeName)}/records${query ?? ""}`;
+  }
+  /** @internal */
+  pExploreTypeEdges(kg) {
+    return `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/type-edges`;
+  }
+  /** @internal */
+  pExploreSearch(query) {
+    return `${this.base()}/explore/search${query}`;
+  }
+  /** @internal */
+  pNormalizeSuggest(query) {
+    return `${this.base()}/normalize/suggest${query}`;
+  }
+  /** @internal */
+  pNormalizeRules(query) {
+    return `${this.base()}/normalize/rules${query ?? ""}`;
+  }
+  /** @internal */
+  pNormalizeRule(ruleId, action) {
+    return `${this.base()}/normalize/rules/${encodeURIComponent(ruleId)}/${action}`;
+  }
+  /** @internal */
+  pTenants() {
+    return `${this.baseUrl}/v1/me/tenants`;
+  }
+  /** @internal */
+  pTenant(tenantId) {
+    return `${this.baseUrl}/v1/me/tenants/${encodeURIComponent(tenantId)}`;
+  }
+  /**
+   * Low-level passthrough request. Centralizes the absolute URL (already built
+   * by a path-builder, so it carries the base URL + `/graphs/{tenant}` prefix),
+   * the `X-API-Key` header, JSON content-type, body stringification, and a
+   * timeout/abort — then returns the backend {@link Response} UNCHANGED.
+   *
+   * Unlike {@link request}, this does NOT inspect `res.ok` and does NOT parse or
+   * reshape the body. A 4xx/5xx comes back as a resolved `Response` (the caller
+   * reads `.status`/`.headers`/`.body`), NOT a thrown {@link CographError}. The
+   * only rejection paths are a genuine network failure or a timeout abort —
+   * exactly the cases where there is no HTTP response to hand back.
+   *
+   * `init.headers` is merged last so a caller can add/override headers; `init.body`,
+   * when a non-string is passed, is JSON-stringified for convenience.
+   */
+  async requestRaw(method, path, init = {}) {
+    const timeoutMs = init.timeoutMs ?? 12e4;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let body;
+    if (init.body !== void 0) {
+      body = typeof init.body === "string" ? init.body : JSON.stringify(init.body);
+    }
+    try {
+      return await fetch(path, {
+        method,
+        headers: { ...this.headers(), ...init.headers ?? {} },
+        body,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new CographError(`Request to ${path} timed out after ${timeoutMs}ms`);
+      }
+      throw new CographError(
+        `Network error contacting ${path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   /**
    * Probe the backend to determine reachability and whether endpoints
    * require an X-API-Key header. Used at shell startup to distinguish
@@ -342,6 +505,41 @@ var Client = class {
     if (opts.model) body.model = opts.model;
     return this.request("POST", `${this.base()}/ask`, body, 6e4);
   }
+  /**
+   * One turn of the unified Ask-AI agent — the SINGLE conversational surface
+   * (`POST /graphs/{tenant}/agent`, COG-118). Mirrors the HTTP contract exactly:
+   *
+   *  - `confirmPlanId` set → the server runs `execute_plan` (the only mutating
+   *    path) and returns `{kind:"result", steps}`.
+   *  - otherwise → the server runs `planner.handle(message)` and returns one of
+   *    `{kind:"answer"}` / `{kind:"clarify"}` / `{kind:"plan"}`.
+   *
+   * The agent classifies intent server-side and drives the underlying engines
+   * through its capability registry — the client never talks to `/ask`,
+   * `/enrich/*` etc. for an agent turn. ENTITLEMENT for any paid step a plan
+   * contains is enforced server-side at execute time (the same authorization the
+   * direct paid routes apply), so confirming a plan here cannot bypass a gate the
+   * direct path enforces — the gate lives behind the endpoint, not in this client.
+   */
+  async agent(opts) {
+    const body = {
+      message: opts.message ?? "",
+      context: {
+        kg_name: opts.kgName ?? "",
+        type_name: opts.typeName ?? null
+      }
+    };
+    if (opts.sessionId) body.session_id = opts.sessionId;
+    if (opts.confirmPlanId) body.confirm = { plan_id: opts.confirmPlanId };
+    return this.request(
+      "POST",
+      `${this.base()}/agent`,
+      body,
+      // Generous: a confirmed plan can kick off enrichment/dedup work, and a
+      // question turn runs an LLM round-trip server-side.
+      12e4
+    );
+  }
   /** List the tenants the authenticated user can access (GET /v1/me/tenants).
    *  Keyed by the API key (X-API-Key → user), so it's independent of the active
    *  tenant. Throws CographError with status 501 on deployments without a tenant
@@ -529,15 +727,273 @@ var Client = class {
     const qs = new URLSearchParams({ kg, q, kind }).toString();
     const data = await this.request(
       "GET",
-      `${this.base()}/explore/search?${qs}`,
+      this.pExploreSearch(`?${qs}`),
       void 0,
       15e3
     );
     return Array.isArray(data) ? data : [];
   }
+  // --- New typed methods (COG-128) ------------------------------------------ #
+  // Parsed/throwing variants of the previously-MISSING ops, sharing the same
+  // path-builders as the raw API. These follow the existing typed-method
+  // contract (throw on non-2xx, light reshape) — the raw equivalents under
+  // `client.raw.*` are the non-throwing, non-reshaping passthrough versions.
+  /**
+   * One page of entity instances of a type for the Explorer Data table
+   * (`GET /explore/kgs/{kg}/types/{type}/records`). Keyset-paginated by entity
+   * URI: pass the previous page's `next_cursor` as `cursor`. `limit` is clamped
+   * server-side to 1..200 (default 50).
+   */
+  async exploreRecords(kg, typeName, opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.limit != null) qs.set("limit", String(opts.limit));
+    if (opts.cursor) qs.set("cursor", opts.cursor);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request(
+      "GET",
+      this.pExploreRecords(kg, typeName, query),
+      void 0,
+      3e4
+    );
+  }
+  /** Undirected type→type edges for the Explorer overview graph
+   *  (`GET /explore/kgs/{kg}/type-edges`). Returns `[{source, target, weight}]`. */
+  async exploreTypeEdges(kg) {
+    const data = await this.request(
+      "GET",
+      this.pExploreTypeEdges(kg),
+      void 0,
+      3e4
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Infer + persist normalization rules for a type's predicates, returned ranked
+   *  by confidence desc (`POST /normalize/suggest?kg&type`). */
+  async normalizeSuggest(kg, type) {
+    const qs = new URLSearchParams({ kg, type }).toString();
+    const data = await this.request(
+      "POST",
+      this.pNormalizeSuggest(`?${qs}`),
+      void 0,
+      6e4
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** List stored normalization rules, optionally filtered by KG and/or status
+   *  (`GET /normalize/rules?kg&status`). */
+  async normalizeRules(opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.kg) qs.set("kg", opts.kg);
+    if (opts.status) qs.set("status", opts.status);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    const data = await this.request(
+      "GET",
+      this.pNormalizeRules(query),
+      void 0,
+      15e3
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Confirm a suggested normalization rule (`POST /normalize/rules/{id}/confirm`). */
+  async normalizeConfirmRule(ruleId) {
+    return this.request(
+      "POST",
+      this.pNormalizeRule(ruleId, "confirm"),
+      void 0,
+      15e3
+    );
+  }
+  /** Reject a suggested normalization rule (`POST /normalize/rules/{id}/reject`). */
+  async normalizeRejectRule(ruleId) {
+    return this.request(
+      "POST",
+      this.pNormalizeRule(ruleId, "reject"),
+      void 0,
+      15e3
+    );
+  }
+  /** Apply a confirmed normalization rule in the background; the server acks 202
+   *  (`POST /normalize/rules/{id}/apply`). */
+  async normalizeApplyRule(ruleId) {
+    return this.request(
+      "POST",
+      this.pNormalizeRule(ruleId, "apply"),
+      {},
+      6e4
+    );
+  }
+  /** Recommend ontology relationships/changes for the active KG
+   *  (`POST /ontology/recommend`). Body shape is passed through unchanged.
+   *
+   *  NOTE: this targets the *premium* ontology-recommender route, which is only
+   *  mounted on deployments carrying the proprietary layer. It 404s on a bare
+   *  OSS deployment. */
+  async ontologyRecommend(body = {}) {
+    return this.request(
+      "POST",
+      this.pOntologyRecommend(),
+      body,
+      6e4
+    );
+  }
+};
+var RawApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  // -- agent / ask --------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/agent` — one turn of the unified Ask-AI agent. */
+  agent(body, init) {
+    return this.client.requestRaw("POST", this.client.pAgent(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ask` — natural-language question. */
+  ask(body, init) {
+    return this.client.requestRaw("POST", this.client.pAsk(), { body, ...init });
+  }
+  // -- ingest -------------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/ingest` — ingest text/json (or csv) content. */
+  ingest(body, init) {
+    return this.client.requestRaw("POST", this.client.pIngest(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ingest/csv/schema` — infer a CSV schema mapping. */
+  ingestCsvSchema(body, init) {
+    return this.client.requestRaw("POST", this.client.pIngestCsvSchema(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ingest/csv/rows` — write a batch of mapped rows. */
+  ingestCsvRows(body, init) {
+    return this.client.requestRaw("POST", this.client.pIngestCsvRows(), { body, ...init });
+  }
+  // -- enrich jobs --------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/enrich/jobs` — plan + run an enrichment job. */
+  enrichCreateJob(body, init) {
+    return this.client.requestRaw("POST", this.client.pEnrichJobs(), { body, ...init });
+  }
+  /** `GET /graphs/{tenant}/enrich/jobs` — list recent enrichment jobs. */
+  enrichJobs(init) {
+    return this.client.requestRaw("GET", this.client.pEnrichJobs(), init);
+  }
+  /** `GET /graphs/{tenant}/enrich/jobs/{id}` — fetch a single job. */
+  enrichJob(jobId, init) {
+    return this.client.requestRaw("GET", this.client.pEnrichJob(jobId), init);
+  }
+  /** `GET /graphs/{tenant}/enrich/jobs/{id}/conflicts` — conflict review queue. */
+  enrichConflicts(jobId, init) {
+    return this.client.requestRaw("GET", this.client.pEnrichJobConflicts(jobId), init);
+  }
+  /** `POST /graphs/{tenant}/enrich/jobs/{id}/apply` — apply review decisions. */
+  enrichApply(jobId, body, init) {
+    return this.client.requestRaw("POST", this.client.pEnrichJobApply(jobId), { body, ...init });
+  }
+  /** `DELETE /graphs/{tenant}/enrich/jobs/{id}` — cancel a job. */
+  enrichCancel(jobId, init) {
+    return this.client.requestRaw("DELETE", this.client.pEnrichJob(jobId), init);
+  }
+  // -- ontology ------------------------------------------------------------ #
+  /** `GET /graphs/{tenant}/ontology/types` — list ontology types. */
+  ontologyTypes(init) {
+    return this.client.requestRaw("GET", this.client.pOntologyTypes(), init);
+  }
+  /** `POST /graphs/{tenant}/ontology/resolve` — resolve an NL ontology change. */
+  ontologyResolve(body, init) {
+    return this.client.requestRaw("POST", this.client.pOntologyResolve(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ontology/recommend` — recommend ontology changes.
+   *  Premium route: only mounted on deployments with the proprietary layer,
+   *  404s on bare OSS. */
+  ontologyRecommend(body, init) {
+    return this.client.requestRaw("POST", this.client.pOntologyRecommend(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ontology/apply` — apply one resolved change. */
+  ontologyApply(body, init) {
+    return this.client.requestRaw("POST", this.client.pOntologyApply(), { body, ...init });
+  }
+  // -- knowledge graphs ---------------------------------------------------- #
+  /** `GET /graphs/{tenant}/kgs` — list knowledge graphs. */
+  kgs(init) {
+    return this.client.requestRaw("GET", this.client.pKgs(), init);
+  }
+  /** `POST /graphs/{tenant}/kgs` — create a knowledge graph. */
+  createKg(body, init) {
+    return this.client.requestRaw("POST", this.client.pKgs(), { body, ...init });
+  }
+  /** `DELETE /graphs/{tenant}/kgs/{name}` — delete a knowledge graph. */
+  deleteKg(name, init) {
+    return this.client.requestRaw("DELETE", this.client.pKg(name), init);
+  }
+  // -- explore ------------------------------------------------------------- #
+  /** `GET /graphs/{tenant}/explore/kgs/{kg}/types/{type}/summary`. */
+  exploreSummary(kg, typeName, init) {
+    return this.client.requestRaw("GET", this.client.pExploreSummary(kg, typeName), init);
+  }
+  /** `GET /graphs/{tenant}/explore/kgs/{kg}/types/{type}/records?limit&cursor`. */
+  exploreRecords(kg, typeName, opts = {}, init) {
+    const qs = new URLSearchParams();
+    if (opts.limit != null) qs.set("limit", String(opts.limit));
+    if (opts.cursor) qs.set("cursor", opts.cursor);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    return this.client.requestRaw("GET", this.client.pExploreRecords(kg, typeName, query), init);
+  }
+  /** `GET /graphs/{tenant}/explore/kgs/{kg}/type-edges`. */
+  exploreTypeEdges(kg, init) {
+    return this.client.requestRaw("GET", this.client.pExploreTypeEdges(kg), init);
+  }
+  /** `GET /graphs/{tenant}/kgs/{kg}/type-counts`. */
+  typeCounts(kg, init) {
+    return this.client.requestRaw("GET", this.client.pTypeCounts(kg), init);
+  }
+  /** `GET /graphs/{tenant}/explore/search?kg&q&kind`. */
+  exploreSearch(kg, q, kind = "type", init) {
+    const qs = new URLSearchParams({ kg, q, kind }).toString();
+    return this.client.requestRaw("GET", this.client.pExploreSearch(`?${qs}`), init);
+  }
+  // -- normalize ----------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/normalize/suggest?kg&type` — infer + persist rules. */
+  normalizeSuggest(kg, type, init) {
+    const qs = new URLSearchParams({ kg, type }).toString();
+    return this.client.requestRaw("POST", this.client.pNormalizeSuggest(`?${qs}`), init);
+  }
+  /** `GET /graphs/{tenant}/normalize/rules?kg&status` — list stored rules. */
+  normalizeRules(opts = {}, init) {
+    const qs = new URLSearchParams();
+    if (opts.kg) qs.set("kg", opts.kg);
+    if (opts.status) qs.set("status", opts.status);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    return this.client.requestRaw("GET", this.client.pNormalizeRules(query), init);
+  }
+  /** `POST /graphs/{tenant}/normalize/rules` — create a user-authored rule. */
+  normalizeCreateRule(body, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRules(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/normalize/rules/{id}/confirm`. */
+  normalizeConfirmRule(ruleId, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRule(ruleId, "confirm"), init);
+  }
+  /** `POST /graphs/{tenant}/normalize/rules/{id}/reject`. */
+  normalizeRejectRule(ruleId, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRule(ruleId, "reject"), init);
+  }
+  /** `POST /graphs/{tenant}/normalize/rules/{id}/apply`. */
+  normalizeApplyRule(ruleId, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRule(ruleId, "apply"), init);
+  }
+  // -- tenants (account-level, NOT tenant-scoped) -------------------------- #
+  /** `POST /v1/me/tenants` — create/grant a tenant for the authed user. */
+  createTenant(body, init) {
+    return this.client.requestRaw("POST", this.client.pTenants(), { body, ...init });
+  }
+  /** `DELETE /v1/me/tenants/{id}` — remove a tenant grant. */
+  deleteTenant(tenantId, init) {
+    return this.client.requestRaw("DELETE", this.client.pTenant(tenantId), init);
+  }
+  /** `GET /v1/me/tenants` — list tenants the authed user can access. */
+  tenants(init) {
+    return this.client.requestRaw("GET", this.client.pTenants(), init);
+  }
 };
 export {
   Client,
-  CographError
+  CographError,
+  RawApi
 };
 //# sourceMappingURL=index.js.map