@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/api/blueprint-authoring-api.ts

@@ -0,0 +1,574 @@
+import { CliError } from '../errors'
+import type { DefinitionBundle } from '../blueprint/model'
+
+/**
+ * Blueprint AUTHORING over HTTP.
+ *
+ * Separate from `PlatformApi`, which reads the workspace's granted slice. Authoring is
+ * organization-grain: the shared draft, its revision lifecycle, and the release it
+ * publishes to. A workspace credential cannot reach any of it — the service refuses a
+ * workspace key at organization scope by design — so these calls need an `sk-org-`
+ * organization key.
+ *
+ * Every mutation carries `expectedRevision`. The draft is shared, so a write that does
+ * not say which revision it was computed against is a lost update waiting to happen;
+ * the service answers 409 when the revision has moved, and the caller re-reads.
+ */
+export class BlueprintAuthoringApi {
+  constructor(
+    private readonly apiBaseUrl: string,
+    private readonly token: string,
+  ) {}
+
+  private async call<T>(
+    path: string,
+    init: { method?: string; body?: unknown } = {},
+  ): Promise<T> {
+    const res = await fetch(`${this.apiBaseUrl}${path}`, {
+      method: init.method ?? 'GET',
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        'content-type': 'application/json',
+      },
+      ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    })
+
+    const text = await res.text()
+    let payload: any = null
+    try { payload = text ? JSON.parse(text) : null } catch { /* non-JSON body */ }
+
+    if (!res.ok) {
+      // The credential failures worth telling apart, because each has a different
+      // fix and a generic "request failed" sends the reader to the wrong one.
+      if (res.status === 401) {
+        throw new CliError(
+          'The credential was refused. An organization key that has been revoked or has ' +
+          'expired reads exactly like this — mint or rotate one in Settings → API keys.',
+          { code: 'UNAUTHORIZED', hint: 'frontera login --api-url <url>' },
+        )
+      }
+      if (res.status === 403) {
+        throw new CliError(
+          payload?.message
+            ? `${payload.message} — the key may not carry the capability this route needs, its `
+              + `creator's role may have changed, or the row is in a workspace the key does not list`
+            : "The key is not permitted to author this organization's Blueprint.",
+          {
+            code: 'FORBIDDEN',
+            // Three distinct causes with three distinct fixes, and the service cannot
+            // tell them apart for us. Naming all three beats naming the wrong one:
+            // a workspace-addressed route refuses a key whose workspace list omits
+            // that workspace, which has nothing to do with organization:update.
+            hint: 'Check the key carries the capability, and — for a workspace- or '
+              + 'agent-addressed route — that its workspace list includes that workspace.',
+          },
+        )
+      }
+      if (res.status === 409) {
+        throw new CliError(
+          payload?.message
+            ?? 'The shared draft moved since this change was computed. Re-run to pick up the current revision.',
+          { code: 'CONFLICT', hint: 'frontera blueprint status' },
+        )
+      }
+      if (res.status === 404) {
+        throw new CliError(payload?.message ?? 'Not found', {
+          code: 'NOT_FOUND',
+          hint: 'frontera blueprint status',
+        })
+      }
+      throw new CliError(payload?.message ?? `${res.status} ${text.slice(0, 200)}`, { code: 'FAILURE', hint: 'frontera blueprint status' })
+    }
+
+    return (payload?.data ?? payload) as T
+  }
+
+  /**
+   * The organization's lifecycle, or `null` when it has no Blueprint yet.
+   *
+   * "Not adopted" is a legitimate state, not an error: it is the state every
+   * organization starts in. Surfacing it as a 404 made `status` — the command whose
+   * whole job is to report the state — fail instead of describing it.
+   */
+  async lifecycleOrNull(): Promise<{
+    draft?: { revision?: number }
+    activeReleaseId?: string
+    activeRelease?: { id?: string; releaseLabel?: string; releaseNumber?: number }
+  } | null> {
+    try {
+      return await this.lifecycle()
+    } catch (err) {
+      const notFound = err instanceof CliError && (err.code === 'NOT_FOUND' || err.code === 'FAILURE')
+      if (notFound) return null
+      throw err
+    }
+  }
+
+  /** The organization's lifecycle: draft revision, active release. */
+  lifecycle(): Promise<{
+    draft?: { revision?: number }
+    activeReleaseId?: string
+    activeRelease?: { id?: string; releaseLabel?: string; releaseNumber?: number }
+  }> {
+    return this.call('/v1/blueprint/lifecycle')
+  }
+
+  /** The draft revision every mutation must be computed against. */
+  async revision(): Promise<number> {
+    const lifecycle = await this.lifecycle()
+    const revision = lifecycle?.draft?.revision
+    if (typeof revision !== 'number') {
+      throw new CliError(
+        'This organization has no Blueprint draft yet — run `frontera blueprint adopt` first.',
+        { code: 'FAILURE', hint: 'frontera blueprint adopt' },
+      )
+    }
+    return revision
+  }
+
+  adopt(): Promise<unknown> {
+    return this.call('/v1/blueprint/lifecycle/adopt', { method: 'POST', body: {} })
+  }
+
+  // ── draft catalog ─────────────────────────────────────────────────────────
+
+  createObjectType(body: Record<string, unknown>, expectedRevision: number) {
+    return this.call('/v1/blueprint/object-types', { method: 'POST', body: { ...body, expectedRevision } })
+  }
+
+  updateObjectType(apiName: string, body: Record<string, unknown>, expectedRevision: number) {
+    return this.call(`/v1/blueprint/object-types/${encodeURIComponent(apiName)}`, {
+      method: 'PUT',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  /** The draft's object type. The route nests it under `objectType`. */
+  async getObjectType(apiName: string): Promise<{ id?: string } | null> {
+    const payload = await this.call<{ objectType?: { id?: string } }>(
+      `/v1/blueprint/object-types/${encodeURIComponent(apiName)}?view=draft`,
+    )
+    return payload?.objectType ?? (payload as { id?: string } | null)
+  }
+
+  /**
+   * The draft object type AND its properties.
+   *
+   * The route answers `{ objectType, properties, draftRevision }` — the properties
+   * are a SIBLING of the object type, not a field on it. `getObjectType` above
+   * returns the nested object alone, which is what a caller wanting an id wants and
+   * exactly wrong for a caller wanting the fields to map.
+   */
+  async getObjectTypeDetail(apiName: string): Promise<{
+    id?: string
+    properties: Array<{ id?: string; apiName?: string }>
+  } | null> {
+    const payload = await this.call<{
+      objectType?: { id?: string }
+      properties?: Array<{ id?: string; apiName?: string }>
+    }>(`/v1/blueprint/object-types/${encodeURIComponent(apiName)}?view=draft`)
+    if (!payload?.objectType?.id) return null
+    return { id: payload.objectType.id, properties: payload.properties ?? [] }
+  }
+
+  /** The draft catalog — what an organization key can actually see. */
+  listObjectTypes(): Promise<Array<{ id?: string; apiName?: string; displayName?: string }>> {
+    return this.call('/v1/blueprint/object-types?view=draft')
+  }
+
+  /** Endpoints return object types by ID, not by API name — see `blueprint catalog`. */
+  listLinkTypes(): Promise<
+    Array<{ apiName?: string; fromObjectTypeId?: string; toObjectTypeId?: string }>
+  > {
+    return this.call('/v1/blueprint/link-types?view=draft')
+  }
+
+  listMetrics(): Promise<
+    Array<{ apiName?: string; displayName?: string; objectTypeId?: string }>
+  > {
+    return this.call('/v1/blueprint/metrics?view=draft')
+  }
+
+  createLinkType(body: Record<string, unknown>, expectedRevision: number) {
+    return this.call('/v1/blueprint/link-types', { method: 'POST', body: { ...body, expectedRevision } })
+  }
+
+  updateLinkType(apiName: string, body: Record<string, unknown>, expectedRevision: number) {
+    return this.call(`/v1/blueprint/link-types/${encodeURIComponent(apiName)}`, {
+      method: 'PUT',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  deleteLinkType(apiName: string, expectedRevision: number) {
+    return this.call(`/v1/blueprint/link-types/${encodeURIComponent(apiName)}`, {
+      method: 'DELETE',
+      body: { expectedRevision },
+    })
+  }
+
+  createMetric(body: Record<string, unknown>, expectedRevision: number) {
+    return this.call('/v1/blueprint/metrics', { method: 'POST', body: { ...body, expectedRevision } })
+  }
+
+  updateMetric(apiName: string, body: Record<string, unknown>, expectedRevision: number) {
+    return this.call(`/v1/blueprint/metrics/${encodeURIComponent(apiName)}`, {
+      method: 'PUT',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  deleteMetric(apiName: string, expectedRevision: number) {
+    return this.call(`/v1/blueprint/metrics/${encodeURIComponent(apiName)}`, {
+      method: 'DELETE',
+      body: { expectedRevision },
+    })
+  }
+
+  // ── shared field types ─────────────────────────────────────────────────
+
+  listSharedProperties(): Promise<
+    Array<{ id?: string; apiName?: string; displayName?: string; dataType?: string }>
+  > {
+    return this.call('/v1/blueprint/shared-fields?view=draft')
+  }
+
+  /**
+   * Create, and read the minted id back.
+   *
+   * The response carries the created row rather than only a revision, and that is
+   * load-bearing: a tree that creates a shared field and the property implementing
+   * it in one `apply` has no id at plan time, so the executor takes it from here. The
+   * CLI never invents one — no other artifact is created that way.
+   */
+  createSharedProperty(
+    body: Record<string, unknown>,
+    expectedRevision: number,
+  ): Promise<{ sharedProperty?: { id?: string; apiName?: string }; draftRevision?: number }> {
+    return this.call('/v1/blueprint/shared-fields', {
+      method: 'POST',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  updateSharedProperty(apiName: string, body: Record<string, unknown>, expectedRevision: number) {
+    return this.call(`/v1/blueprint/shared-fields/${encodeURIComponent(apiName)}`, {
+      method: 'PUT',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  /** Succeeds with implementers: each reverts to a regular property keeping its values. */
+  deleteSharedProperty(apiName: string, expectedRevision: number) {
+    return this.call(`/v1/blueprint/shared-fields/${encodeURIComponent(apiName)}`, {
+      method: 'DELETE',
+      body: { expectedRevision },
+    })
+  }
+
+  /**
+   * Removing an object type is a STRUCTURAL change, so it goes through preview and
+   * apply rather than a plain DELETE: the service refuses an apply whose digest does
+   * not match the preview it was shown, which is what stops a change from landing
+   * differently to how it was reviewed.
+   */
+  async removeObject(
+    objectId: string,
+    expectedRevision: number,
+  ): Promise<{ preview: unknown; applied: unknown; revision: number }> {
+    return this.draftCommand({ kind: 'remove_object', objectId }, expectedRevision)
+  }
+
+  // ── release lifecycle ─────────────────────────────────────────────────────
+
+  validate(): Promise<{ id?: string; reportId?: string }> {
+    return this.call('/v1/blueprint/lifecycle/validate', { method: 'POST', body: {} })
+  }
+
+  publish(input: {
+    expectedRevision: number
+    validationReportId: string
+    releaseLabel: string
+    releaseNotes: string
+    instruction?: string
+  }) {
+    const { instruction, ...body } = input
+    // Publish REQUIRES the field even when empty; rollback treats it as optional.
+    // Dropping the default here failed typebox before authorization ever ran.
+    return this.postWithMigrations(
+      '/v1/blueprint/lifecycle/publish',
+      { migrationInstructions: [], ...body },
+      instruction,
+    )
+  }
+
+  /**
+   * POST a release operation, negotiating migration instructions once.
+   *
+   * A release that discards changes is refused until each discarded change carries an
+   * explanation, and the service names the change ids it wants. Rather than make the
+   * caller guess them, this asks, then retries with one instruction per named change.
+   * Shared by publish and rollback because the refusal is identical for both.
+   */
+  private async postWithMigrations(
+    path: string,
+    body: Record<string, unknown>,
+    instruction?: string,
+  ): Promise<unknown> {
+    try {
+      return await this.call(path, { method: 'POST', body })
+    } catch (err) {
+      if (!(err instanceof CliError) || err.code !== 'CONFLICT' || !instruction) throw err
+      const changeIds = await this.migrationBlockers(path, body)
+      if (changeIds.length === 0) throw err
+      return this.call(path, {
+        method: 'POST',
+        body: {
+          ...body,
+          migrationInstructions: changeIds.map((changeId) => ({ changeId, instruction })),
+        },
+      })
+    }
+  }
+
+  /**
+   * Roll back to an earlier release.
+   *
+   * The service refuses when discarded changes need an explanation, and names the
+   * change ids it wants covered. Rather than make the caller guess, this asks once
+   * and retries with an instruction per named change when `instruction` is given.
+   */
+  async rollback(
+    releaseId: string,
+    input: { releaseLabel: string; releaseNotes: string; instruction?: string },
+  ): Promise<unknown> {
+    return this.postWithMigrations(
+      `/v1/blueprint/lifecycle/releases/${encodeURIComponent(releaseId)}/rollback`,
+      { releaseLabel: input.releaseLabel, releaseNotes: input.releaseNotes },
+      input.instruction,
+    )
+  }
+
+  // ── the whole draft, for pull / plan ──────────────────────────────────────
+
+  /**
+   * The draft's definition bundle and the revision it is at, in one read.
+   *
+   * `plan` needs both and must see them from a single observation: reading the
+   * definition and then the revision separately would let the draft move between the
+   * two, and the plan would be computed against a bundle the revision no longer
+   * describes.
+   */
+  async draft(): Promise<{ definition: DefinitionBundle; revision: number }> {
+    const lifecycle = await this.call<{
+      draft?: { revision?: number; definition?: DefinitionBundle }
+    }>('/v1/blueprint/lifecycle')
+    const revision = lifecycle?.draft?.revision
+    const definition = lifecycle?.draft?.definition
+    if (typeof revision !== 'number' || !definition) {
+      throw new CliError(
+        'This organization has no Blueprint draft yet.',
+        { code: 'FAILURE', hint: 'frontera blueprint adopt' },
+      )
+    }
+    return { definition, revision }
+  }
+
+  // ── actions ───────────────────────────────────────────────────────────────
+
+  listActions(): Promise<Array<{ apiName?: string; displayName?: string }>> {
+    return this.call('/v1/blueprint/actions?view=draft')
+  }
+
+  createAction(action: Record<string, unknown>, expectedRevision: number) {
+    return this.call('/v1/blueprint/actions', { method: 'POST', body: { expectedRevision, action } })
+  }
+
+  updateAction(apiName: string, action: Record<string, unknown>, expectedRevision: number) {
+    return this.call(`/v1/blueprint/actions/${encodeURIComponent(apiName)}`, {
+      method: 'PUT',
+      body: { expectedRevision, action },
+    })
+  }
+
+  deleteAction(apiName: string, expectedRevision: number) {
+    return this.call(`/v1/blueprint/actions/${encodeURIComponent(apiName)}`, {
+      method: 'DELETE',
+      body: { expectedRevision },
+    })
+  }
+
+  // ── object sets ───────────────────────────────────────────────────────────
+
+  listObjectSets(): Promise<Array<{ id?: string; name?: string; kind?: string }>> {
+    return this.call('/v1/blueprint/object-sets')
+  }
+
+  createObjectSet(body: Record<string, unknown>) {
+    return this.call('/v1/blueprint/object-sets', { method: 'POST', body })
+  }
+
+  updateObjectSet(id: string, body: Record<string, unknown>) {
+    return this.call(`/v1/blueprint/object-sets/${encodeURIComponent(id)}`, { method: 'PUT', body })
+  }
+
+  deleteObjectSet(id: string) {
+    return this.call(`/v1/blueprint/object-sets/${encodeURIComponent(id)}`, { method: 'DELETE' })
+  }
+
+  // ── grants, and the names they are addressed by ───────────────────────────
+
+  orgWorkspaces(): Promise<Array<{ id?: string; name?: string; slug?: string }>> {
+    return this.call('/v1/blueprint/org-workspaces')
+  }
+
+  orgAgents(): Promise<Array<{ id?: string; name?: string }>> {
+    return this.call('/v1/blueprint/org-agents')
+  }
+
+  workspaceGrants(workspaceId: string): Promise<Array<{ objectTypeApiName?: string }>> {
+    return this.call(`/v1/blueprint/grants/workspace/${encodeURIComponent(workspaceId)}`)
+  }
+
+  agentGrants(agentId: string): Promise<Array<{ objectTypeApiName?: string }>> {
+    return this.call(`/v1/blueprint/grants/agent/${encodeURIComponent(agentId)}`)
+  }
+
+  grantWorkspace(workspaceId: string, objectTypeApiName: string) {
+    return this.call('/v1/blueprint/grants/workspace', {
+      method: 'POST',
+      body: { workspaceId, objectTypeApiName },
+    })
+  }
+
+  revokeWorkspace(workspaceId: string, objectTypeApiName: string) {
+    return this.call(
+      `/v1/blueprint/grants/workspace/${encodeURIComponent(workspaceId)}/${encodeURIComponent(objectTypeApiName)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  grantAgent(agentId: string, objectTypeApiName: string) {
+    return this.call('/v1/blueprint/grants/agent', {
+      method: 'POST',
+      body: { agentId, objectTypeApiName },
+    })
+  }
+
+  revokeAgent(agentId: string, objectTypeApiName: string) {
+    return this.call(
+      `/v1/blueprint/grants/agent/${encodeURIComponent(agentId)}/${encodeURIComponent(objectTypeApiName)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  // ── datasets: read-only, and reachable because the key holds `dataset:read` ─
+
+  /**
+   * Datasets live on `/v1/data-integration`, not on the Blueprint router. No lane
+   * declaration opens them: the organization-key lane refuses undeclared WRITES and
+   * UNGATED reads, and these are gated — so the only requirement is that the key was
+   * minted carrying `dataset: ['read']`.
+   */
+  async listDatasets(): Promise<Array<{ id?: string; name?: string; currentRevisionId?: string }>> {
+    // Every page, not the first. The route defaults to 50 and answers `nextCursor`;
+    // stopping at one page made dataset 51 report "No dataset named X" and made
+    // `pull` omit its backing silently, because the omission warning keys on having
+    // found NO names rather than on having stopped early.
+    const all: Array<{ id?: string; name?: string; currentRevisionId?: string }> = []
+    let cursor: string | undefined
+    do {
+      const page = await this.call<{
+        items?: Array<{
+          id?: string
+          apiName?: string
+          currentRevision?: { id?: string }
+          currentRevisionId?: string
+        }>
+        nextCursor?: string | null
+      }>(`/v1/data-integration/datasets${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ''}`)
+      for (const dataset of page?.items ?? []) {
+        all.push({
+          ...(dataset.id === undefined ? {} : { id: dataset.id }),
+          ...(dataset.apiName === undefined ? {} : { name: dataset.apiName }),
+          // The route SAYS which revision is current. Deriving it by sorting
+          // revisions descending is a different answer after a rollback, and `bind`
+          // would pin the wrong one.
+          ...(dataset.currentRevision?.id ?? dataset.currentRevisionId
+            ? { currentRevisionId: dataset.currentRevision?.id ?? dataset.currentRevisionId }
+            : {}),
+        })
+      }
+      cursor = page?.nextCursor ?? undefined
+    } while (cursor)
+    return all
+  }
+
+  async datasetRevisions(datasetId: string): Promise<Array<{
+    id?: string
+    revision?: number
+    schemaDigest?: string
+    columns?: Array<{ name?: string; type?: unknown; nullable?: boolean }>
+  }>> {
+    const page = await this.call<{ items?: Array<{ id?: string; revision?: number }> }>(
+      `/v1/data-integration/datasets/${encodeURIComponent(datasetId)}/revisions`,
+    )
+    // Highest revision first. This orders the LIST; which revision is CURRENT comes
+    // from the dataset itself (`currentRevisionId`), because after a rollback the
+    // highest-numbered revision is not the live one.
+    return [...(page?.items ?? [])].sort((left, right) => (right.revision ?? 0) - (left.revision ?? 0))
+  }
+
+  // ── object draft commands ─────────────────────────────────────────────────
+
+  /**
+   * Preview a command, then apply the exact thing that was previewed.
+   *
+   * Every impactful object change travels this pair — `rename_object_api`,
+   * `set_editable_properties`, `update_source_binding`, the field operations and
+   * `remove_object`. The service refuses an apply whose digest does not match the
+   * preview it showed, which is what stops a change landing differently to how it was
+   * reviewed.
+   */
+  async draftCommand(
+    command: Record<string, unknown>,
+    expectedRevision: number,
+  ): Promise<{ preview: unknown; applied: unknown; revision: number }> {
+    const preview = await this.call<{ previewDigest?: string; digest?: string }>(
+      '/v1/blueprint/object-draft-commands/preview',
+      { method: 'POST', body: { expectedRevision, command } },
+    )
+    const applied = await this.call<{ draftRevision?: number }>(
+      '/v1/blueprint/object-draft-commands/apply',
+      {
+        method: 'POST',
+        body: { expectedRevision, command, previewDigest: preview?.previewDigest ?? preview?.digest },
+      },
+    )
+    return { preview, applied, revision: applied?.draftRevision ?? expectedRevision + 1 }
+  }
+
+
+
+  /** Append-only. A property that already exists is changed by a field command. */
+  addProperty(objectTypeApiName: string, body: Record<string, unknown>, expectedRevision: number) {
+    return this.call(
+      `/v1/blueprint/object-types/${encodeURIComponent(objectTypeApiName)}/properties`,
+      { method: 'POST', body: { ...body, expectedRevision } },
+    )
+  }
+
+  /** The change ids a blocked release operation wants instructions for. */
+  private async migrationBlockers(path: string, body: Record<string, unknown>): Promise<string[]> {
+    const res = await fetch(`${this.apiBaseUrl}${path}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    const payload: any = await res.json().catch(() => null)
+    const blockers: Array<{ code?: string; changeId?: string }> = payload?.details?.blockers ?? []
+    return blockers
+      .filter((b) => b.code === 'MIGRATION_INSTRUCTION_REQUIRED' && b.changeId)
+      .map((b) => b.changeId!)
+  }
+}