@useatlas/types - npm Package Compare versions

Comparing version 0.4.0 to 0.5.0

dist/knowledge.d.ts

+/**
+ * Wire types for the Knowledge Base admin surface (`/admin/knowledge`, #4209,
+ * ADR-0028).
+ *
+ * A *collection* is a `pillar='knowledge'` `workspace_plugins` install whose
+ * `install_id` is the slug; *documents* are hosted-OKF markdown files that
+ * ingest into it as content-mode drafts. Returned by the
+ * `/api/v1/admin/knowledge` routes and consumed by the admin UI (a pure HTTP
+ * client — it never imports `@atlas/api`).
+ */
+/** Supported OKF bundle archive formats — the one place this union is named. */
+export type KnowledgeBundleFormat = "tar" | "tar.gz" | "zip";
+/** Per-status document counts for one collection. */
+export interface KnowledgeDocumentCounts {
+    readonly draft: number;
+    readonly published: number;
+    readonly archived: number;
+}
+/**
+ * How a collection's content arrives: `upload` (the `okf-upload` catalog row —
+ * explicit admin bundle uploads) or `bundle-sync` (the #4211 catalog row — a
+ * scheduled pull of a configured bundle endpoint).
+ */
+export type KnowledgeCollectionSource = "upload" | "bundle-sync";
+/**
+ * Bundle-endpoint auth schemes for `bundle-sync` collections — the one wire
+ * home for this union (the server's `BUNDLE_SYNC_AUTH_SCHEMES` tuple and the
+ * web mirrors derive from it). `none` = public endpoint, no credential row.
+ */
+export type KnowledgeSyncAuthScheme = "none" | "bearer" | "basic";
+/**
+ * Last-sync bookkeeping for a `bundle-sync` collection (#4211). Absent (null
+ * on the collection) until the first sync attempt.
+ */
+export interface KnowledgeCollectionSyncStatus {
+    /** ISO-8601 completion time of the last sync attempt (success or error). */
+    readonly lastSyncAt: string;
+    readonly status: "success" | "error";
+    /** Actionable failure message when the last attempt errored. */
+    readonly error: string | null;
+}
+/**
+ * One collection in the workspace's Knowledge Base, as returned by
+ * `GET /api/v1/admin/knowledge`. Archived collections are excluded.
+ */
+export interface KnowledgeCollection {
+    /** Collection slug = `workspace_plugins.install_id`. */
+    readonly slug: string;
+    readonly source: KnowledgeCollectionSource;
+    /** Optional human description from the install config. */
+    readonly description: string | null;
+    /** ISO-8601 install timestamp, or null if unavailable. */
+    readonly installedAt: string | null;
+    /** The configured bundle endpoint (non-secret) — `bundle-sync` only. */
+    readonly endpointUrl: string | null;
+    /**
+     * Configured endpoint auth scheme (non-secret; the secret itself is never
+     * echoed) — `bundle-sync` only, null for upload collections. Pre-fills the
+     * edit-sync-settings dialog so a secret rotation doesn't require re-picking
+     * the scheme. Optional so a response from an older API during a
+     * deploy-overlap window still parses.
+     */
+    readonly authScheme?: KnowledgeSyncAuthScheme | null;
+    /** Last-sync bookkeeping — `bundle-sync` only, null before the first sync. */
+    readonly sync: KnowledgeCollectionSyncStatus | null;
+    readonly documents: KnowledgeDocumentCounts;
+}
+/** `GET /api/v1/admin/knowledge` response. */
+export interface KnowledgeCollectionListResponse {
+    readonly collections: ReadonlyArray<KnowledgeCollection>;
+}
+/**
+ * A document inside a collection, as returned by
+ * `GET /api/v1/admin/knowledge/{slug}/documents`. Archived documents are
+ * excluded, so `status` is only ever `draft` or `published`.
+ */
+export interface KnowledgeDocumentSummary {
+    readonly id: string;
+    /** Bundle path within the collection tree (unique per collection). */
+    readonly path: string;
+    readonly title: string | null;
+    readonly description: string | null;
+    /** OKF document `type` frontmatter, if present. */
+    readonly type: string | null;
+    readonly tags: ReadonlyArray<string>;
+    readonly status: "draft" | "published";
+    /** ISO-8601 last-updated timestamp, or null. */
+    readonly updatedAt: string | null;
+}
+/** `GET /api/v1/admin/knowledge/{slug}/documents` response. */
+export interface KnowledgeDocumentListResponse {
+    readonly collection: string;
+    readonly documents: ReadonlyArray<KnowledgeDocumentSummary>;
+}
+/** A single file the ingest rejected, with a human-readable reason. */
+export interface KnowledgeRejectedFile {
+    readonly path: string;
+    readonly reason: string;
+}
+/** Per-outcome document counts from an ingest run. */
+export interface KnowledgeIngestDocumentCounts {
+    readonly created: number;
+    readonly updated: number;
+    readonly demoted: number;
+    readonly resurrected: number;
+    readonly unchanged: number;
+    readonly total: number;
+}
+/**
+ * `POST /api/v1/admin/knowledge/{slug}/ingest` success response. `published`
+ * reflects whether the request ran the atomic "upload & publish" promotion.
+ */
+export interface KnowledgeIngestSummary {
+    readonly collection: string;
+    readonly format: KnowledgeBundleFormat;
+    readonly documents: KnowledgeIngestDocumentCounts;
+    readonly linksWritten: number;
+    readonly published: boolean;
+    readonly rejected: ReadonlyArray<KnowledgeRejectedFile>;
+    /**
+     * Non-markdown / asset files skipped by design (only `.md` ingests).
+     * Reserved OKF navigation files (`index.md` / `log.md`) are also excluded
+     * from ingest but are NOT counted here.
+     */
+    readonly skippedNonMarkdown: number;
+}
+/** `DELETE /api/v1/admin/knowledge/{slug}` response. */
+export interface KnowledgeUninstallResponse {
+    readonly archived: boolean;
+    readonly collection: string;
+    readonly archivedDocuments: number;
+}
+/**
+ * `POST /api/v1/admin/knowledge/{slug}/sync` response (#4211) — the outcome of
+ * one manual "Sync now" pull. A failed fetch/ingest is still a 200 with
+ * `status: "error"` and an actionable message (the attempt itself completed
+ * and was recorded on the collection's sync status); the ingest fields are
+ * null in that case.
+ */
+export interface KnowledgeSyncRunResponse {
+    readonly collection: string;
+    readonly status: "success" | "error";
+    /** ISO-8601 completion time of this attempt. */
+    readonly syncedAt: string;
+    readonly error: string | null;
+    readonly format: KnowledgeBundleFormat | null;
+    readonly documents: KnowledgeIngestDocumentCounts | null;
+    /** Previously-ingested docs archived because their path left the bundle. */
+    readonly archivedAbsent: number | null;
+    readonly linksWritten: number | null;
+    readonly rejected: ReadonlyArray<KnowledgeRejectedFile>;
+}

dist/index.d.ts

@@ -33,2 +33,3 @@ export * from "./auth";
 export * from "./mode";
+export * from "./knowledge";
 export * from "./starter-prompt";
@@ -35,0 +36,0 @@ export * from "./integrations";

dist/mcp.d.ts

@@ -143,2 +143,7 @@ /**
  *   - `policy`      — governance-*raising* tools (approval rules, PII classes, Phase 4)
+ *   - `raw_sql`     — caller-authored raw SQL over the programmatic surfaces
+ *     (CLI `atlas sql`, MCP `executeSQL`). The *read/query* category (#4095):
+ *     the mutation categories above govern writes, this governs the advanced
+ *     read surface. Disabling it restricts members to the NL `atlas query`
+ *     path; the Atlas agent / chat / `atlas query` are never gated by it.
  *
@@ -151,3 +156,3 @@ * Type-only here (no value tuple) so `@atlas/web` shares the union without
  */
-export type McpActionCategory = "datasource" | "integration" | "policy";
+export type McpActionCategory = "datasource" | "integration" | "policy" | "raw_sql";
 /**
@@ -154,0 +159,0 @@ * Stored state of one category for a workspace. The default posture is

dist/mode.d.ts

@@ -25,2 +25,4 @@ /**
     readonly starterPrompts: number;
+    /** Draft hosted-OKF knowledge documents (status = 'draft'), #4206 / ADR-0028. */
+    readonly knowledgeDocuments: number;
 }
@@ -57,2 +59,5 @@ /**
     };
+    readonly knowledgeDocuments: {
+        readonly lastEditedAt: string | null;
+    };
 }
@@ -82,1 +87,45 @@ /**
 }
+/**
+ * Per-content-type promotion counts returned by the atomic publish operation
+ * (#4126) — one number per promotable content surface, i.e. one per
+ * content-mode registry entry (the API derives this shape from the registry
+ * via `InferPromotedCounts` and drift-checks it at compile time). A subset of
+ * {@link ModeDraftCounts}: that type's `entityEdits` fold into `entities`, and
+ * its `entityDeletes` become the separate {@link PublishResult.deleted}
+ * `entities` count.
+ */
+export interface PublishPromotedCounts {
+    /** Datasource connections promoted `draft` → `published`. */
+    readonly connections: number;
+    /** Semantic entities promoted. */
+    readonly entities: number;
+    /** Prompt collections promoted. */
+    readonly prompts: number;
+    /** Starter-prompt suggestions promoted. */
+    readonly starterPrompts: number;
+    /** Hosted-OKF knowledge documents promoted (#4206, ADR-0028). */
+    readonly knowledgeDocuments: number;
+}
+/**
+ * Shared wire type for the atomic publish operation's result — the single
+ * shape every publish surface keys off (#4156). Returned by the atomic publish
+ * endpoint (`POST /api/v1/admin/publish`), the MCP `publish_datasources` tool,
+ * and `atlas datasource publish` — all of which promote the same workspace-wide
+ * drafts and so must report the same counts.
+ *
+ * The delete-count field is `deleted.entities` on EVERY surface (this closes the
+ * pre-#4156 drift where REST used `deleted.entities`, MCP `deleted_entities`, and
+ * the lib `deletedEntities`). Surfaces that carry MORE than the shared core
+ * extend this type rather than reshaping it: the REST response adds `archived`
+ * (its phase-4 connection cascade) + `warnings` (partial-profile markers); the
+ * MCP tool adds `published: true`; the lib returns exactly this core.
+ */
+export interface PublishResult {
+    /** Per-content-type counts promoted `draft` → `published`. */
+    readonly promoted: PublishPromotedCounts;
+    /** Published rows removed by applying `draft_delete` tombstones. */
+    readonly deleted: {
+        /** Published entities superseded/removed by the promotion's tombstones. */
+        readonly entities: number;
+    };
+}

package.json

 {
   "name": "@useatlas/types",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Shared types for the Atlas text-to-SQL agent",
@@ -5,0 +5,0 @@ "type": "module",

No alert changes

Improved metrics

Total package byte prevSize

278346

3.47%

Number of package files

72

1.41%

Lines of code

6703

3.19%

No dependency changes