@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/api/dataset-api.ts

@@ -0,0 +1,199 @@
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+
+import { CliError } from '../errors'
+
+/**
+ * Datasets, from the CLI.
+ *
+ * The reason this exists is the one `secret` states for itself: a Blueprint object type
+ * names the dataset it reads — `backing.dataset` — and until now the CLI could author
+ * that object type while nothing could create the dataset it named. The dataset had to
+ * be made in the Console by hand, which is the one step an FDE deploying an
+ * organization could not script. `bind` presumed it; `apply` failed at it.
+ *
+ * All three forms the Console offers are here, because all three are things an FDE has
+ * to be able to do without opening it:
+ *
+ *   BLANK declares a column contract and carries no rows. It is the only one a
+ *   committed tree can fully describe, and the only one a Blueprint binding strictly
+ *   needs — the pinned revision an object type reads is a contract, not data.
+ *
+ *   SOURCE pulls a relation from a connected Source. The Source itself is still made
+ *   elsewhere; this names one that exists.
+ *
+ *   FILE uploads a CSV. The bytes live outside the tree by nature, so the file is named
+ *   by path and never inlined.
+ *
+ * `uploadPreview` exists because the file form must declare `includedColumns` and
+ * nobody can write that list before seeing what the CSV actually holds.
+ */
+
+interface Options {
+  method?: string
+  body?: unknown
+  /** Multipart. Never set alongside `body` — the two choose different content types. */
+  form?: FormData
+}
+
+export interface SourceSummary {
+  id?: string
+  displayName?: string
+  connectorType?: string
+  status?: string
+  currentRevision?: { id?: string; revision?: number }
+}
+
+/** A test that could not connect still answers 200 — the verdict is in the body. */
+export interface ConnectionTest {
+  status?: string
+  errorCode?: string | null
+  errorMessage?: string | null
+  latencyMs?: number
+  latestConnectionTest?: { status?: string; errorCode?: string | null; errorMessage?: string | null }
+}
+
+export interface UploadPreview {
+  columns?: Array<{ name?: string; databaseType?: string; nullable?: boolean; ordinal?: number }>
+  rowCount?: number
+}
+
+export interface DatasetColumn {
+  name: string
+  databaseType: 'text' | 'numeric' | 'boolean' | 'date' | 'timestamptz'
+  nullable: boolean
+}
+
+export interface DatasetSummary {
+  id?: string
+  apiName?: string
+  name?: string
+  displayName?: string
+  description?: string | null
+  currentRevisionId?: string
+  updatedAt?: string
+}
+
+export interface DatasetRevision {
+  id?: string
+  revision?: number
+  schemaDigest?: string
+  columns?: Array<{ name?: string; databaseType?: string; nullable?: boolean }>
+}
+
+export class DatasetApi {
+  constructor(private readonly apiUrl: string, private readonly token: string) {}
+
+  private async call<T>(path: string, options: Options = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl}${path}`, {
+      method: options.form ? 'POST' : (options.method ?? 'GET'),
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        // Never set for multipart: `fetch` writes the boundary itself, and a
+        // hand-written Content-Type loses it and the body parses as nothing.
+        ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(options.form ? { body: options.form } : {}),
+      ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+    })
+    const text = await response.text()
+    const payload = text ? JSON.parse(text) : {}
+    if (!response.ok) {
+      throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {
+        code: payload?.code ?? 'FAILURE',
+        ...(payload?.details ? { hint: JSON.stringify(payload.details) } : {}),
+      })
+    }
+    return (payload?.data ?? payload) as T
+  }
+
+  /** These routes paginate as `{ items, nextCursor }`; callers want rows. */
+  private async page<T>(path: string): Promise<T[]> {
+    const body = await this.call<{ items?: T[] } | T[]>(path)
+    return Array.isArray(body) ? body : (body.items ?? [])
+  }
+
+  list(): Promise<DatasetSummary[]> {
+    return this.page<DatasetSummary>('/v1/data-integration/datasets')
+  }
+
+  get(datasetId: string): Promise<DatasetSummary> {
+    return this.call<DatasetSummary>(`/v1/data-integration/datasets/${encodeURIComponent(datasetId)}`)
+  }
+
+  revisions(datasetId: string): Promise<DatasetRevision[]> {
+    return this.page<DatasetRevision>(
+      `/v1/data-integration/datasets/${encodeURIComponent(datasetId)}/revisions`,
+    )
+  }
+
+  listSources(): Promise<SourceSummary[]> {
+    return this.page<SourceSummary>('/v1/data-integration/sources')
+  }
+
+  /** Columns and a sample, read from the CSV before anything is created. */
+  async uploadPreview(path: string): Promise<UploadPreview> {
+    const form = new FormData()
+    form.append('file', new Blob([readFileSync(path)]), basename(path))
+    return this.call<UploadPreview>('/v1/data-integration/datasets/upload-preview', { form })
+  }
+
+  /**
+   * Verify a Source revision can be reached.
+   *
+   * `from-source` refuses a revision without a latest verified test, so this is part of
+   * the create path rather than a diagnostic. It writes a test result and moves no data.
+   */
+  testSourceRevision(revisionId: string): Promise<ConnectionTest> {
+    return this.call<ConnectionTest>(
+      `/v1/data-integration/source-revisions/${encodeURIComponent(revisionId)}/test`,
+      { method: 'POST' },
+    )
+  }
+
+  createFromSource(payload: {
+    apiName: string
+    displayName: string
+    description?: string | null
+    sourceId: string
+    schema: string
+    relation: string
+    includedColumns: string[]
+    keyColumns: string[] | null
+    deterministicKeyConfirmed: boolean
+  }): Promise<DatasetSummary> {
+    return this.call<DatasetSummary>('/v1/data-integration/datasets/from-source', {
+      method: 'POST',
+      body: payload,
+    })
+  }
+
+  /** Multipart: the CSV alongside a JSON `payload` part, which is how the route reads it. */
+  createFromFile(path: string, payload: {
+    apiName: string
+    displayName: string
+    description?: string | null
+    includedColumns: string[]
+    keyColumns: string[] | null
+    deterministicKeyConfirmed: boolean
+  }): Promise<DatasetSummary> {
+    const form = new FormData()
+    form.append('file', new Blob([readFileSync(path)]), basename(path))
+    form.append('payload', JSON.stringify(payload))
+    return this.call<DatasetSummary>('/v1/data-integration/datasets/from-file', { form })
+  }
+
+  createBlank(payload: {
+    apiName: string
+    displayName: string
+    description?: string | null
+    columns: DatasetColumn[]
+    keyColumns: string[] | null
+    deterministicKeyConfirmed: boolean
+  }): Promise<DatasetSummary> {
+    return this.call<DatasetSummary>('/v1/data-integration/datasets/blank', {
+      method: 'POST',
+      body: payload,
+    })
+  }
+}

package/src/api/platform-api.ts

@@ -1,5 +1,24 @@
 import { FronteraClient } from '@frontera-sdk/core/client'
 
+import { CliError } from '../errors'
+
+/**
+ * The service's code for an HTTP status, for responses that carry no `code` of
+ * their own — the upload route answers 415 with a bare `{ error }`. Mapped to
+ * the same strings `exitCodeFor` already classifies, so an auth failure exits 4
+ * ("no retry helps") rather than 1 ("transient").
+ */
+function statusCode(status: number): string {
+  if (status === 401) return 'UNAUTHORIZED'
+  if (status === 403) return 'FORBIDDEN'
+  if (status === 404) return 'NOT_FOUND'
+  if (status === 409) return 'CONFLICT'
+  if (status === 415 || status === 400 || status === 422) return 'BAD_REQUEST'
+  if (status === 429) return 'RATE_LIMITED'
+  if (status === 503) return 'SERVICE_UNAVAILABLE'
+  return 'FAILURE'
+}
+
 export interface AgentDraft {
   agentId?: string
   revision: number
@@ -164,6 +183,76 @@ export class PlatformApi {
     return this.get<unknown>(`/v1/config/workspace-skills/${encodeURIComponent(id)}`)
   }
 
+  /** Bulk upsert (by name). The route validates asset storage keys, script
+   *  limits and paths — the CLI does not duplicate those rules. */
+  importWorkspaceSkills(skills: unknown[]) {
+    return this.client.request<{ created: number; updated: number; errors: Array<{ name: string; message: string }> }>(
+      '/v1/config/workspace-skills/import',
+      { method: 'POST', body: { skills } },
+    )
+  }
+
+  private authHeader(): Record<string, string> {
+    const c = this.client.config.credential
+    return { authorization: `Bearer ${c.kind === 'apiKey' ? c.key : c.token}` }
+  }
+
+  /**
+   * Upload one skill asset. Multipart lives here, not in the SDK transport,
+   * for the same reason as `AppsApi.multipart` — the shared transport is
+   * JSON-only on purpose.
+   */
+  async uploadSkillAsset(
+    bytes: Uint8Array,
+    filename: string,
+    mime: string,
+  ): Promise<{ storagePath: string; mediaType: string }> {
+    const form = new FormData()
+    form.set('file', new File([new Blob([bytes.buffer as ArrayBuffer])], filename, { type: mime }))
+    form.set('purpose', 'skill-asset')
+    const res = await fetch(`${this.client.config.apiBaseUrl}/v1/upload`, {
+      method: 'POST',
+      headers: this.authHeader(),
+      body: form,
+    })
+    const text = await res.text()
+    let parsed: unknown = null
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      parsed = text
+    }
+    if (!res.ok) {
+      // Not a plain `Error`. Thrown bare, an auth failure here reached the
+      // renderer with no code, was reported as INTERNAL_ERROR and exited 1 —
+      // "transient, retry" — so a caller retried an upload that no retry could
+      // ever fix. The status carries the only fact that decides the exit code.
+      const body = parsed as { message?: string; error?: string; code?: string } | null
+      throw new CliError(
+        body?.message ?? body?.error ?? `asset upload failed with ${res.status}`,
+        {
+          code: body?.code ?? statusCode(res.status),
+          ...(res.status === 401
+            ? { hint: 'set FRONTERA_TOKEN to a valid sk-ws- workspace key, or run `frontera login`' }
+            : {}),
+        },
+      )
+    }
+    const envelope = parsed as { data?: { storagePath: string; mediaType: string } }
+    const data = envelope?.data ?? (parsed as { storagePath: string; mediaType: string })
+    return data
+  }
+
+  /** Fetch one skill asset's bytes by workspace + `{sha}.{ext}` filename. */
+  async downloadSkillAsset(workspaceId: string, filename: string): Promise<Uint8Array> {
+    const res = await fetch(
+      `${this.client.config.apiBaseUrl}/v1/skill-assets/${encodeURIComponent(workspaceId)}/${encodeURIComponent(filename)}`,
+      { headers: this.authHeader() },
+    )
+    if (!res.ok) throw new Error(`asset download failed with ${res.status} (${filename})`)
+    return new Uint8Array(await res.arrayBuffer())
+  }
+
   // ── Plugins (integrations and MCP servers) ────────────────────────────────
 
   pluginInstalls() {
@@ -190,4 +279,215 @@ export class PlatformApi {
   knowledgeSources(id: string) {
     return this.getList<unknown>(`/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`)
   }
+
+  /**
+   * Create a workspace knowledge base.
+   *
+   * Only name and description travel. Embedding model, chunker and retrieval
+   * all have service-side defaults, and a CLI flag for each would let a caller
+   * build a base whose vectors no other base can be compared against — a
+   * choice that belongs to whoever operates the workspace, not to whoever is
+   * seeding files into it today.
+   */
+  createKnowledgeBase(workspaceId: string, body: { name: string; description?: string }) {
+    return this.client.request<unknown>('/v1/workspace-knowledge', {
+      method: 'POST',
+      body: { workspaceId, ...body },
+    })
+  }
+
+  /**
+   * Upload one file into a knowledge base.
+   *
+   * Multipart, so it goes through `fetch` directly rather than the shared
+   * transport, for the same reason as `uploadSkillAsset`.
+   *
+   * Ingestion is asynchronous: a 201 means the source row exists and the
+   * Inngest job is queued, NOT that the file is searchable. `frontera
+   * knowledge sources` is where the outcome shows up.
+   */
+  async uploadKnowledgeSource(
+    baseId: string,
+    file: { bytes: Uint8Array; filename: string; mime: string },
+    opts: { extractionStrategy?: string } = {},
+  ): Promise<{ id?: string; status?: string }> {
+    const form = new FormData()
+    form.set(
+      'file',
+      new File([new Blob([file.bytes.buffer as ArrayBuffer])], file.filename, { type: file.mime }),
+    )
+    if (opts.extractionStrategy) form.set('extractionStrategy', opts.extractionStrategy)
+
+    const res = await fetch(
+      `${this.client.config.apiBaseUrl}/v1/workspace-knowledge/${encodeURIComponent(baseId)}/sources`,
+      { method: 'POST', headers: this.authHeader(), body: form },
+    )
+    const text = await res.text()
+    let parsed: unknown = null
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      parsed = text
+    }
+    if (!res.ok) {
+      // The upload route answers 415 with `{ error: "Unsupported file type…" }`
+      // and the quota gate with the platform's `{ message }` envelope, so both
+      // keys have to be read or the useful sentence is replaced by a number.
+      const body = parsed as { message?: string; error?: string } | null
+      throw new Error(body?.message ?? body?.error ?? `upload failed with ${res.status}`)
+    }
+    // `created(source)` wraps `{ source, … }`, and the envelope is stripped by
+    // neither `fetch` nor the SDK here — unwrap both layers, tolerating either.
+    const envelope = parsed as { data?: { source?: { id?: string; status?: string } } } | null
+    const source = envelope?.data?.source ?? (envelope?.data as { id?: string } | undefined)
+    return (source ?? {}) as { id?: string; status?: string }
+  }
+
+  /** Give an agent access to a knowledge base. Idempotent server-side. */
+  attachKnowledgeAgent(baseId: string, agentId: string) {
+    return this.client.request<unknown>(
+      `/v1/workspace-knowledge/${encodeURIComponent(baseId)}/agents`,
+      { method: 'POST', body: { agentId } },
+    )
+  }
+
+  /** Take that access away. The base and its sources are untouched. */
+  detachKnowledgeAgent(baseId: string, agentId: string) {
+    return this.client.request<unknown>(
+      `/v1/workspace-knowledge/${encodeURIComponent(baseId)}/agents/${encodeURIComponent(agentId)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  /**
+   * Create an agent.
+   *
+   * It lands in `configuring` with an empty draft, which is why `agent list`
+   * does not show it: that route lists agents with a published version. The
+   * chain from here is `agent apply` then `agent publish`, and both resolve a
+   * slug through `GET /config/agents/:ref`, which does see it.
+   */
+  createAgent(body: {
+    agentId: string
+    name?: string
+    description?: string
+    kind?: 'conversation' | 'work'
+  }) {
+    return this.client.request<unknown>('/v1/config/agents', { method: 'POST', body })
+  }
+
+  /** Remove a workspace skill. Bindings to agents go with it. */
+  deleteWorkspaceSkill(id: string) {
+    return this.client.request<unknown>(
+      `/v1/config/workspace-skills/${encodeURIComponent(id)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  // ── Packs ─────────────────────────────────────────────────────────────────
+
+  /** Every pack in the org, each with this workspace's install row or null. */
+  packs() {
+    return this.getList<unknown>('/v1/packs/')
+  }
+
+  async pack(packId: string): Promise<Record<string, unknown>> {
+    const body = await this.get<{ data?: Record<string, unknown> } | Record<string, unknown>>(
+      `/v1/packs/${encodeURIComponent(packId)}`,
+    )
+    return ((body as { data?: Record<string, unknown> })?.data ?? body ?? {}) as Record<string, unknown>
+  }
+
+  createPack(manifest: unknown) {
+    return this.client.request<unknown>('/v1/packs/', { method: 'POST', body: { manifest } })
+  }
+
+  updatePack(packId: string, manifest: unknown) {
+    return this.client.request<unknown>(`/v1/packs/${encodeURIComponent(packId)}`, {
+      method: 'PUT',
+      body: { manifest },
+    })
+  }
+
+  deletePack(packId: string) {
+    return this.client.request<unknown>(`/v1/packs/${encodeURIComponent(packId)}`, {
+      method: 'DELETE',
+    })
+  }
+
+  installPack(packId: string) {
+    return this.client.request<unknown>(`/v1/packs/${encodeURIComponent(packId)}/install`, {
+      method: 'POST',
+    })
+  }
+
+  /** `removeApps` also uninstalls the apps the pack brought in. Default false. */
+  uninstallPack(packId: string, removeApps = false) {
+    return this.client.request<unknown>(`/v1/packs/${encodeURIComponent(packId)}/uninstall`, {
+      method: 'POST',
+      body: { removeApps },
+    })
+  }
+
+  /** Install puts the skills in the workspace; this is what an AGENT loads. */
+  applyPackToAgent(packId: string, agentId: string) {
+    return this.client.request<unknown>(
+      `/v1/packs/${encodeURIComponent(packId)}/agents/${encodeURIComponent(agentId)}/apply`,
+      { method: 'POST' },
+    )
+  }
+
+  removePackFromAgent(packId: string, agentId: string) {
+    return this.client.request<unknown>(
+      `/v1/packs/${encodeURIComponent(packId)}/agents/${encodeURIComponent(agentId)}/apply`,
+      { method: 'DELETE' },
+    )
+  }
+
+  // ── Workspace secrets ─────────────────────────────────────────────────────
+
+  /**
+   * Secret NAMES and what depends on each. Values are never returned by this
+   * route — not to a session and not to a key.
+   */
+  workspaceSecrets(workspaceId: string) {
+    return this.getList<unknown>(`/v1/workspaces/${encodeURIComponent(workspaceId)}/secrets`)
+  }
+
+  createWorkspaceSecret(
+    workspaceId: string,
+    body: { name: string; value: string; description?: string },
+  ) {
+    return this.client.request<unknown>(
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/secrets`,
+      { method: 'POST', body },
+    )
+  }
+
+  /** Replace the value of a secret that already exists. */
+  updateWorkspaceSecret(
+    workspaceId: string,
+    name: string,
+    body: { value?: string; description?: string },
+  ) {
+    return this.client.request<unknown>(
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/secrets/${encodeURIComponent(name)}`,
+      { method: 'PATCH', body },
+    )
+  }
+
+  /** Refused server-side while anything still resolves the secret. */
+  deleteWorkspaceSecret(workspaceId: string, name: string) {
+    return this.client.request<unknown>(
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/secrets/${encodeURIComponent(name)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  /** Which agents can read this base. */
+  knowledgeAttachments(baseId: string) {
+    return this.getList<unknown>(
+      `/v1/workspace-knowledge/${encodeURIComponent(baseId)}/agents`,
+    )
+  }
 }