@opengeni/sdk 3.3.2-canary.1 → 3.4.0

package/src/document-authority-client.ts

@@ -1,5 +1,13 @@
+import type { CompanyBrainOkfDownload, CompanyBrainOkfPackage } from "./company-brain";
 import { OpenGeniClient as OpenGeniCoreClient } from "./client";
 import type {
+  ApiKey,
+  UpdateOrganizationApiKeyRequest,
+  Document,
+  IssueUserResourceGrantRequest,
+  UserResourceGrantMutationResponse,
+  DocumentBase,
+  FileDownloadUrlResponse,
   DocumentAuthorityReclassification,
   DocumentDefaultCollectionBackfill,
   DocumentDefaultCollectionBackfillAudit,
@@ -13,13 +21,108 @@ import type {
 } from "./types";
 
 /**
- * Operator-only Document authority and tenancy-backfill surface.
+ * Operator-only authority administration and Document tenancy-backfill surface.
  *
  * The public root and legacy `core` clients extend this class for compatibility.
  * Browser consoles that import `@opengeni/sdk/browser` do not retain these
  * methods or their routes.
  */
 export class OpenGeniDocumentAuthorityClient extends OpenGeniCoreClient {
+  /** Read organization-key metadata and policy; never returns the secret token. */
+  async getOrganizationApiKey(organizationId: string, apiKeyId: string): Promise<ApiKey> {
+    return await this.requestJson<ApiKey>(
+      "GET",
+      `/v1/organizations/${organizationId}/api-keys/${apiKeyId}`,
+    );
+  }
+
+  /** Update metadata or replace the policy. Policy narrowing applies on the next request. */
+  async updateOrganizationApiKey(
+    organizationId: string,
+    apiKeyId: string,
+    request: UpdateOrganizationApiKeyRequest,
+  ): Promise<ApiKey> {
+    return await this.requestJson<ApiKey>(
+      "PATCH",
+      `/v1/organizations/${organizationId}/api-keys/${apiKeyId}`,
+      request,
+    );
+  }
+
+  /** Issue an exact-session or standing personal-resource grant. */
+  async issueUserResourceGrant(
+    workspaceId: string,
+    authorityId: string,
+    request: IssueUserResourceGrantRequest,
+  ): Promise<UserResourceGrantMutationResponse> {
+    return await this.requestJson<UserResourceGrantMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/user-resource-authorities/${authorityId}/grants`,
+      request,
+    );
+  }
+
+  async listDocumentBases(workspaceId: string): Promise<DocumentBase[]> {
+    return await this.requestJson<DocumentBase[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases`,
+    );
+  }
+
+  /**
+   * List every Document the current human can manage from this workspace,
+   * including portable personal and organization-scoped Documents whose
+   * immutable ingestion workspace is different.
+   */
+  async listAccessibleDocuments(workspaceId: string): Promise<Document[]> {
+    return await this.requestJson<Document[]>("GET", `/v1/workspaces/${workspaceId}/documents`);
+  }
+
+  /** Mint a source-file URL through the Document's effective authority. */
+  async createDocumentOriginalFileDownloadUrl(
+    workspaceId: string,
+    documentId: string,
+  ): Promise<FileDownloadUrlResponse> {
+    return await this.requestJson<FileDownloadUrlResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/original-file/download-url`,
+    );
+  }
+
+  /** Retry indexing for a failed document. */
+  async reindexDocument(
+    workspaceId: string,
+    baseId: string,
+    documentId: string,
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}/reindex`,
+    );
+  }
+
+  /** Permission-filtered Company Brain package with authorized guidance bodies. */
+  getCompanyBrain(workspaceId: string): Promise<CompanyBrainOkfPackage> {
+    return this.requestJson<CompanyBrainOkfPackage>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/company-brain`,
+    );
+  }
+
+  /** Download the deterministic Markdown/YAML Company Brain package. */
+  async exportCompanyBrainOkf(workspaceId: string): Promise<CompanyBrainOkfDownload> {
+    const response = await this.requestResponse(
+      "GET",
+      `/v1/workspaces/${workspaceId}/company-brain/export`,
+    );
+    const headers = response.headers;
+    return {
+      content: await response.text(),
+      contentType: headers.get("content-type") ?? "text/markdown",
+      filename: headers.get("content-disposition")?.split('"')[1] ?? "company-brain.okf.md",
+    };
+  }
+
   /**
    * Atomically reclassify a Document's authority and every indexed chunk.
    * The operation is replay-safe and rejects a stale expected authority tuple.

package/src/editable-artifacts/controller.ts

@@ -378,6 +378,15 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
   }
 
   getView(): EditableArtifactSyncView {
+    const blockedPending = this.allBlockedPending();
+    const authoringBlockedReason =
+      this.modality !== "spreadsheet" && blockedPending.length > 0
+        ? "pending_conflict"
+        : this.orderedPending().some(
+              (transaction) => transaction.replicaId !== this.writerReplicaId,
+            )
+          ? "prior_writer"
+          : undefined;
     return {
       artifactId: this.artifactId,
       modality: this.modality,
@@ -386,7 +395,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       headSequence: this.headSequence,
       writable: this.writable,
       pendingTransactions: this.pending.size,
-      blockedPending: this.allBlockedPending(),
+      blockedPending,
+      authoringBlockedReason,
       queuedMessages: this.liveQueue.length,
       reconnectAttempt: this.reconnectAttempt,
       lastError: this.lastError,
@@ -714,8 +724,15 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       stored.snapshot.modality === "spreadsheet" ? stored.snapshot.causalFrontier : null;
     let nativeRevision =
       stored.snapshot.modality === "spreadsheet" ? null : stored.snapshot.nativeRevision;
+    const retainedAcceptances: {
+      transaction: EditableArtifactCommittedTransaction;
+      pending: Pick<
+        EditableArtifactPendingTransaction,
+        "clientTransactionId" | "requestHash" | "intentBytes"
+      >;
+    }[] = [];
     for (const transaction of stored.tail) {
-      validateCommittedTransaction(
+      const embeddedPending = validateCommittedTransaction(
         transaction,
         this.artifactId,
         this.modality,
@@ -728,6 +745,15 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       requireStateHash(transaction.priorStateHash, stateHash, "retained transaction prior state");
       const applied = await this.kernel.applyRecovered(transaction);
       requireStateHash(applied.stateHash, transaction.stateHash, "retained transaction");
+      if (embeddedPending) {
+        const pending = this.pending.get(embeddedPending.clientTransactionId);
+        if (
+          pending?.requestHash === embeddedPending.requestHash &&
+          bytesEqual(pending.intentBytes, embeddedPending.intentBytes)
+        ) {
+          retainedAcceptances.push({ transaction, pending: embeddedPending });
+        }
+      }
       cursor = transaction.endSequence;
       stateHash = transaction.stateHash;
       if (transaction.modality === "spreadsheet") {
@@ -763,6 +789,14 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.retainedTailTransactions = stored.tail.length;
     this.cursor = cursor;
     this.headSequence = cursor;
+    // Reload may interrupt between retaining a commit and deleting its WAL entry.
+    // Only settle exact embedded identities after the entire retained head verifies;
+    // otherwise speculative replay mistakes our own committed edit for a conflict.
+    // Callers restore the pending overlay after this confirmed projection is ready.
+    for (const { transaction, pending } of retainedAcceptances) {
+      this.recordAcceptedMappingIdentity(transaction.transactionId, pending);
+      await this.settlePending(transaction, true);
+    }
   }
 
   private async run(): Promise<void> {

package/src/editable-artifacts/index.ts

@@ -99,6 +99,7 @@ export type {
   EditablePresentationSlideCatalogProjection,
   EditablePresentationSlideCatalogQuery,
   EditableSpreadsheetCellValue,
+  EditableSpreadsheetDimensions,
   EditableSpreadsheetFormulaError,
   EditableSpreadsheetMetadataProjection,
   EditableSpreadsheetMetadataQuery,

package/src/editable-artifacts/types.ts

@@ -176,18 +176,28 @@ export type EditableSpreadsheetProjectedCell = Readonly<{
  * Immutable projection of one exact speculative kernel revision. Cells are
  * sparse, strictly row-major, unique, and all inside the requested rectangle.
  */
-export type EditableSpreadsheetViewportProjection = Readonly<{
-  revision: bigint;
-  sheetId: string;
-  /** Creation operation that pins the live CRDT generation, if collaborative. */
-  generationId: string | null;
-  startRow: number;
-  startColumn: number;
-  rowCount: number;
-  columnCount: number;
-  cells: readonly EditableSpreadsheetProjectedCell[];
+export type EditableSpreadsheetDimensions = Readonly<{
+  /** Integer CSS pixels. Present when the kernel models dimensions. */
+  defaultRowHeight?: number;
+  defaultColumnWidth?: number;
+  /** Sorted sparse absolute zero-based indices and non-default pixel sizes. */
+  rowHeights?: readonly (readonly [number, number])[];
+  columnWidths?: readonly (readonly [number, number])[];
 }>;
 
+export type EditableSpreadsheetViewportProjection = EditableSpreadsheetDimensions &
+  Readonly<{
+    revision: bigint;
+    sheetId: string;
+    /** Creation operation that pins the live CRDT generation, if collaborative. */
+    generationId: string | null;
+    startRow: number;
+    startColumn: number;
+    rowCount: number;
+    columnCount: number;
+    cells: readonly EditableSpreadsheetProjectedCell[];
+  }>;
+
 export type EditableSpreadsheetUsedBounds = Readonly<{
   startRow: number;
   startColumn: number;
@@ -197,12 +207,13 @@ export type EditableSpreadsheetUsedBounds = Readonly<{
   endColumn: number;
 }>;
 
-export type EditableSpreadsheetSheetMetadata = Readonly<{
-  sheetId: string;
-  generationId: string | null;
-  name: string;
-  usedBounds: EditableSpreadsheetUsedBounds | null;
-}>;
+export type EditableSpreadsheetSheetMetadata = EditableSpreadsheetDimensions &
+  Readonly<{
+    sheetId: string;
+    generationId: string | null;
+    name: string;
+    usedBounds: EditableSpreadsheetUsedBounds | null;
+  }>;
 
 /**
  * Bounded workbook catalog from the Worker-owned kernel. False feature flags
@@ -479,6 +490,8 @@ export type EditableArtifactSyncView = {
   writable: boolean;
   pendingTransactions: number;
   blockedPending: readonly EditableArtifactBlockedPending[];
+  /** A command barrier independent of the artifact's edit permission. */
+  authoringBlockedReason?: "pending_conflict" | "prior_writer" | undefined;
   queuedMessages: number;
   reconnectAttempt: number;
   lastError: Error | null;