cograph 0.1.25 → 0.1.28

package/dist/index.d.ts

@@ -47,9 +47,39 @@ declare class Client {
     apiKey: string | undefined;
     baseUrl: string;
     tenant: string;
+    /**
+     * 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.
+     */
+    readonly raw: RawApi;
     constructor(opts?: ClientOptions);
     private headers;
     private base;
+    /**
+     * 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.
+     */
+    requestRaw(method: string, path: string, init?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<Response>;
     /**
      * Probe the backend to determine reachability and whether endpoints
      * require an X-API-Key header. Used at shell startup to distinguish
@@ -154,6 +184,42 @@ declare class Client {
     typeSummary(kg: string, typeName: string): Promise<TypeSummary>;
     /** Search types or attributes by name substring within a KG. */
     exploreSearch(kg: string, q: string, kind?: "type" | "attr"): Promise<Array<Record<string, unknown>>>;
+    /**
+     * 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).
+     */
+    exploreRecords(kg: string, typeName: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<TypeRecordsPage>;
+    /** Undirected type→type edges for the Explorer overview graph
+     *  (`GET /explore/kgs/{kg}/type-edges`). Returns `[{source, target, weight}]`. */
+    exploreTypeEdges(kg: string): Promise<TypeEdge[]>;
+    /** Infer + persist normalization rules for a type's predicates, returned ranked
+     *  by confidence desc (`POST /normalize/suggest?kg&type`). */
+    normalizeSuggest(kg: string, type: string): Promise<NormalizationRule[]>;
+    /** List stored normalization rules, optionally filtered by KG and/or status
+     *  (`GET /normalize/rules?kg&status`). */
+    normalizeRules(opts?: {
+        kg?: string;
+        status?: string;
+    }): Promise<NormalizationRule[]>;
+    /** Confirm a suggested normalization rule (`POST /normalize/rules/{id}/confirm`). */
+    normalizeConfirmRule(ruleId: string): Promise<NormalizationRule>;
+    /** Reject a suggested normalization rule (`POST /normalize/rules/{id}/reject`). */
+    normalizeRejectRule(ruleId: string): Promise<NormalizationRule>;
+    /** Apply a confirmed normalization rule in the background; the server acks 202
+     *  (`POST /normalize/rules/{id}/apply`). */
+    normalizeApplyRule(ruleId: string): Promise<Record<string, unknown>>;
+    /** 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. */
+    ontologyRecommend(body?: Record<string, unknown>): Promise<Record<string, unknown>>;
 }
 /**
  * A single ontology change resolved against the existing schema. The same
@@ -329,5 +395,158 @@ interface AgentResult {
     kind: "answer" | "clarify" | "plan" | "result" | "error";
     [key: string]: unknown;
 }
+/** One row in the Explorer Data table — an entity instance with its attribute
+ *  values. `id` is the entity URI; `name` is the display name; the remaining
+ *  keys are per-attribute values (all stringly-typed for display). */
+interface TypeRecord {
+    id: string;
+    name: string;
+    [attr: string]: string;
+}
+/** A page of {@link TypeRecord}s returned by {@link Client.exploreRecords}.
+ *  `next_cursor` is the last entity URI of this page; pass it back as `cursor`
+ *  to fetch the following page, or `null` when there are no more rows. */
+interface TypeRecordsPage {
+    columns: string[];
+    rows: TypeRecord[];
+    total: number;
+    next_cursor: string | null;
+}
+/** An undirected type→type edge in the Explorer overview graph, weighted by the
+ *  number of instance relationships it summarizes. */
+interface TypeEdge {
+    source: string;
+    target: string;
+    weight: number;
+}
+/** A stored normalization rule (suggested / confirmed / rejected / applied).
+ *  Open beyond the documented fields because the rule's `params` shape varies by
+ *  `rule_type` (e.g. `strip_emoji`, `list_explode`). */
+interface NormalizationRule {
+    id: string;
+    kg_name: string;
+    type_name: string;
+    predicate: string;
+    rule_type: string;
+    target_kind?: string;
+    params?: Record<string, unknown>;
+    confidence?: number;
+    rationale?: string;
+    status: "suggested" | "confirmed" | "rejected" | "applied" | string;
+    created_at?: string;
+    applied_at?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Raw / passthrough surface — reached via {@link Client.raw}. Each method maps
+ * to ONE canonical backend operation, builds the path internally (callers pass
+ * NO path string), and returns the backend {@link Response} VERBATIM:
+ *
+ *  - it does NOT throw on a non-2xx status (a 404/500 resolves as a `Response`
+ *    whose `.status` the caller inspects — contrast the typed methods, which
+ *    throw {@link CographError}); and
+ *  - it does NOT parse or reshape the body (the caller gets the unread stream;
+ *    contrast e.g. {@link Client.listKgs}, which unwraps `{kgs:[]}`).
+ *
+ * Every method funnels through {@link Client.requestRaw}, so the base URL,
+ * `X-API-Key`, `/graphs/{tenant}` prefix, JSON content-type and timeout are
+ * centralized in exactly one place. The only rejection paths are a network
+ * failure or a timeout — the cases where there is no HTTP response to return.
+ *
+ * @example
+ * ```ts
+ * const client = new Client({ apiKey, tenant });
+ * // Webapp proxy pattern: forward the backend response 1:1, no reshaping.
+ * const res = await client.raw.enrichJobs(); // GET …/enrich/jobs
+ * return new Response(res.body, { status: res.status, headers: res.headers });
+ *
+ * // A non-2xx is a Response, not a throw:
+ * const r = await client.raw.enrichJob("does-not-exist");
+ * if (r.status === 404) { ... }            // no try/catch needed
+ * ```
+ */
+declare class RawApi {
+    private readonly client;
+    constructor(client: Client);
+    /** `POST /graphs/{tenant}/agent` — one turn of the unified Ask-AI agent. */
+    agent(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ask` — natural-language question. */
+    ask(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ingest` — ingest text/json (or csv) content. */
+    ingest(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ingest/csv/schema` — infer a CSV schema mapping. */
+    ingestCsvSchema(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ingest/csv/rows` — write a batch of mapped rows. */
+    ingestCsvRows(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/enrich/jobs` — plan + run an enrichment job. */
+    enrichCreateJob(body: unknown, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/enrich/jobs` — list recent enrichment jobs. */
+    enrichJobs(init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/enrich/jobs/{id}` — fetch a single job. */
+    enrichJob(jobId: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/enrich/jobs/{id}/conflicts` — conflict review queue. */
+    enrichConflicts(jobId: string, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/enrich/jobs/{id}/apply` — apply review decisions. */
+    enrichApply(jobId: string, body: unknown, init?: RawInit): Promise<Response>;
+    /** `DELETE /graphs/{tenant}/enrich/jobs/{id}` — cancel a job. */
+    enrichCancel(jobId: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/ontology/types` — list ontology types. */
+    ontologyTypes(init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ontology/resolve` — resolve an NL ontology change. */
+    ontologyResolve(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ontology/recommend` — recommend ontology changes.
+     *  Premium route: only mounted on deployments with the proprietary layer,
+     *  404s on bare OSS. */
+    ontologyRecommend(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/ontology/apply` — apply one resolved change. */
+    ontologyApply(body: unknown, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/kgs` — list knowledge graphs. */
+    kgs(init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/kgs` — create a knowledge graph. */
+    createKg(body: unknown, init?: RawInit): Promise<Response>;
+    /** `DELETE /graphs/{tenant}/kgs/{name}` — delete a knowledge graph. */
+    deleteKg(name: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/explore/kgs/{kg}/types/{type}/summary`. */
+    exploreSummary(kg: string, typeName: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/explore/kgs/{kg}/types/{type}/records?limit&cursor`. */
+    exploreRecords(kg: string, typeName: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/explore/kgs/{kg}/type-edges`. */
+    exploreTypeEdges(kg: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/kgs/{kg}/type-counts`. */
+    typeCounts(kg: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/explore/search?kg&q&kind`. */
+    exploreSearch(kg: string, q: string, kind?: "type" | "attr", init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/normalize/suggest?kg&type` — infer + persist rules. */
+    normalizeSuggest(kg: string, type: string, init?: RawInit): Promise<Response>;
+    /** `GET /graphs/{tenant}/normalize/rules?kg&status` — list stored rules. */
+    normalizeRules(opts?: {
+        kg?: string;
+        status?: string;
+    }, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/normalize/rules` — create a user-authored rule. */
+    normalizeCreateRule(body: unknown, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/normalize/rules/{id}/confirm`. */
+    normalizeConfirmRule(ruleId: string, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/normalize/rules/{id}/reject`. */
+    normalizeRejectRule(ruleId: string, init?: RawInit): Promise<Response>;
+    /** `POST /graphs/{tenant}/normalize/rules/{id}/apply`. */
+    normalizeApplyRule(ruleId: string, init?: RawInit): Promise<Response>;
+    /** `POST /v1/me/tenants` — create/grant a tenant for the authed user. */
+    createTenant(body: unknown, init?: RawInit): Promise<Response>;
+    /** `DELETE /v1/me/tenants/{id}` — remove a tenant grant. */
+    deleteTenant(tenantId: string, init?: RawInit): Promise<Response>;
+    /** `GET /v1/me/tenants` — list tenants the authed user can access. */
+    tenants(init?: RawInit): Promise<Response>;
+}
+/** Per-call overrides for a {@link RawApi} method — extra/override headers and a
+ *  custom timeout. A `body` here is ignored by methods that take an explicit
+ *  body argument (they set it themselves). */
+interface RawInit {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
 
-export { type AgentResult, type AgentTurnOptions, type AskOptions, Client, type ClientOptions, CographError, type ConflictPolicy, type ConflictReview, type EnrichJob, type EnrichJobCreate, type EnrichRequest, type EnrichmentTier, type IngestOptions, type JobProgress, type JobStatus, type JobSummary, type OntologyApplyResult, type OntologyResolveResult, type ResolvedChange, type ReviewDecision, type RowAction, type RowResult, type Verdict };
+export { type AgentResult, type AgentTurnOptions, type AskOptions, Client, type ClientOptions, CographError, type ConflictPolicy, type ConflictReview, type EnrichJob, type EnrichJobCreate, type EnrichRequest, type EnrichmentTier, type IngestOptions, type JobProgress, type JobStatus, type JobSummary, type NormalizationRule, type OntologyApplyResult, type OntologyResolveResult, RawApi, type RawInit, type ResolvedChange, type ReviewDecision, type RowAction, type RowResult, type TypeEdge, type TypeRecord, type TypeRecordsPage, type Verdict };