Curate strict public SDK declarations

package.json

@@ -7,6 +7,15 @@
     "url": "https://github.com/Fairmint/ocp-canton-sdk.git"
   },
   "license": "GPL-3.0-only",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [

scripts/check-declarations.ts

@@ -5,7 +5,11 @@ import ts from 'typescript';
 const projectRoot = process.cwd();
 const configPath = path.join(projectRoot, 'tsconfig.json');
 const declarationEntryPoint = path.join(projectRoot, 'dist', 'index.d.ts');
+const strictConsumerEntryPoint = path.join(projectRoot, 'test', 'declarations', 'publicApi.types.ts');
 const declarationRoot = `${path.dirname(declarationEntryPoint)}${path.sep}`;
+const generatedDamlPackage = '@fairmint/open-captable-protocol-daml-js';
+const cantonTransactionTreeOperationsModule = '@fairmint/canton-node-sdk/build/src/clients/ledger-json-api/operations';
+const commonTypesDeclaration = path.join(declarationRoot, 'types', 'common.d.ts');
 const diagnosticHost: ts.FormatDiagnosticsHost = {
   getCanonicalFileName: (fileName) => fileName,
   getCurrentDirectory: () => projectRoot,
@@ -30,16 +34,41 @@ if (parsedConfig.errors.length > 0) {
 }
 
 const program = ts.createProgram({
-  rootNames: [declarationEntryPoint],
-  options: parsedConfig.options,
+  rootNames: [declarationEntryPoint, strictConsumerEntryPoint],
+  options: { ...parsedConfig.options, rootDir: projectRoot },
 });
 
-const sdkDiagnostics = ts
-  .getPreEmitDiagnostics(program)
-  .filter((diagnostic) => diagnostic.file?.fileName.startsWith(declarationRoot));
+const diagnostics = ts.getPreEmitDiagnostics(program);
 
-if (sdkDiagnostics.length > 0) {
+if (diagnostics.length > 0) {
   throw new Error(
-    `SDK declaration validation failed:\n${ts.formatDiagnosticsWithColorAndContext(sdkDiagnostics, diagnosticHost)}`
+    `Strict consumer declaration validation failed:\n${ts.formatDiagnosticsWithColorAndContext(diagnostics, diagnosticHost)}`
+  );
+}
+
+const generatedDamlLeaks = program
+  .getSourceFiles()
+  .filter((sourceFile) => sourceFile.fileName.startsWith(declarationRoot))
+  .filter((sourceFile) => sourceFile.text.includes(generatedDamlPackage))
+  .map((sourceFile) => path.relative(projectRoot, sourceFile.fileName));
+
+if (generatedDamlLeaks.length > 0) {
+  throw new Error(
+    `Public declaration graph references ${generatedDamlPackage}:\n${generatedDamlLeaks.map((file) => `- ${file}`).join('\n')}`
+  );
+}
+
+const duplicatedTransactionTreeResponseImports = program
+  .getSourceFiles()
+  .filter((sourceFile) => sourceFile.fileName.startsWith(declarationRoot))
+  .filter((sourceFile) => sourceFile.fileName !== commonTypesDeclaration)
+  .filter((sourceFile) => sourceFile.text.includes(cantonTransactionTreeOperationsModule))
+  .map((sourceFile) => path.relative(projectRoot, sourceFile.fileName));
+
+if (duplicatedTransactionTreeResponseImports.length > 0) {
+  throw new Error(
+    `Public declarations must import transaction-tree response types through src/types/common:\n${duplicatedTransactionTreeResponseImports
+      .map((file) => `- ${file}`)
+      .join('\n')}`
   );
 }

src/OcpClient.ts

@@ -68,35 +68,38 @@ import {
   type OcpEnvironment,
 } from './environment';
 import { OcpErrorCodes, OcpValidationError } from './errors';
-import {
-  authorizeIssuer,
-  buildCreateIssuerCommand,
-  getEntityAsOcf,
-  withdrawAuthorization,
-  type AuthorizeIssuerParams,
-  type AuthorizeIssuerResult,
-  type CreateIssuerParams,
-  type WithdrawAuthorizationParams,
-  type WithdrawAuthorizationResult,
-} from './functions';
 import {
   archiveCapTable,
-  CapTableBatch,
-  classifyIssuerCapTables,
-  getCapTableState,
-  mapOcfObjectTypeToEntityType,
   type ArchiveCapTableParams,
   type ArchiveCapTableResult,
-  type CapTableState,
-  type IssuerCapTableClassification,
+} from './functions/OpenCapTable/capTable/archiveCapTable';
+import { CapTableBatch, type CapTableBatchParams } from './functions/OpenCapTable/capTable/CapTableBatch';
+import { getEntityAsOcf } from './functions/OpenCapTable/capTable/damlToOcf';
+import {
+  mapOcfObjectTypeToEntityType,
   type OcfDataTypeFor,
   type OcfEntityType,
   type OcfReadableDataForObjectType,
   type OcfReadableObjectType,
-} from './functions/OpenCapTable/capTable';
+} from './functions/OpenCapTable/capTable/entityTypes';
+import {
+  classifyIssuerCapTables,
+  getCapTableState,
+  type CapTableState,
+  type IssuerCapTableClassification,
+} from './functions/OpenCapTable/capTable/getCapTableState';
+import { buildCreateIssuerCommand } from './functions/OpenCapTable/issuer/api';
+import type { CreateIssuerParams } from './functions/OpenCapTable/issuer/types';
+import { authorizeIssuer } from './functions/OpenCapTable/issuerAuthorization/authorizeIssuer';
+import type {
+  AuthorizeIssuerParams,
+  AuthorizeIssuerResult,
+  WithdrawAuthorizationParams,
+  WithdrawAuthorizationResult,
+} from './functions/OpenCapTable/issuerAuthorization/types';
+import { withdrawAuthorization } from './functions/OpenCapTable/issuerAuthorization/withdrawAuthorization';
 import { mergeCommandContext, type CommandObservabilityOptions, type OcpObservabilityOptions } from './observability';
-import type { CommandWithDisclosedContracts } from './types';
-import type { ContractResult, GetByContractIdParams } from './types/common';
+import type { CommandWithDisclosedContracts, ContractResult, GetByContractIdParams } from './types/common';
 import type {
   OcfConvertibleAcceptanceOutput,
   OcfConvertibleCancellationOutput,
@@ -827,21 +830,7 @@ export interface GetByObjectTypeParams<
 }
 
 /** Parameters for creating a batch cap table update */
-interface CapTableUpdateParams extends CommandObservabilityOptions {
-  /** The contract ID of the CapTable to update */
-  capTableContractId: string;
-  /** Optional contract details for the CapTable (used to get correct templateId from ledger) */
-  capTableContractDetails?: { templateId: string };
-  /**
-   * Optional deterministic command ID for idempotent retry handling.
-   * Takes precedence over `defaultContext.commandId` and `context.commandId`.
-   */
-  commandId?: string;
-  /** Party IDs to act as (signatories) */
-  actAs: string[];
-  /** Optional additional party IDs for read access */
-  readAs?: string[];
-}
+type CapTableUpdateParams = CapTableBatchParams;
 
 /** Entity namespace with a single `get()` method */
 interface EntityReader<T> {

src/functions/OpenCapTable/capTable/CapTableBatch.ts

@@ -7,38 +7,35 @@
 
 import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk/build/src/clients/ledger-json-api';
 import type { Command } from '@fairmint/canton-node-sdk/build/src/clients/ledger-json-api/schemas/api/commands';
-import { Fairmint, OCP_TEMPLATES } from '@fairmint/open-captable-protocol-daml-js';
+import { OCP_TEMPLATES } from '@fairmint/open-captable-protocol-daml-js';
 import { OcpContractError, OcpErrorCodes, OcpValidationError } from '../../../errors';
 import {
   mergeCommandContext,
   submitObservedTransactionTree,
   type CommandObservabilityOptions,
 } from '../../../observability';
-import type { CommandWithDisclosedContracts } from '../../../types';
+import type { CommandWithDisclosedContracts } from '../../../types/common';
+import { type OcfCreateData, type OcfDeleteData, type OcfEditData, type UpdateCapTableResult } from './batchTypes';
 import {
-  ENTITY_TAG_MAP,
-  isOcfCreatableEntityType,
   isOcfDeletableEntityType,
-  isOcfEditableEntityType,
   type CapTableBatchExecuteResult,
   type CapTableBatchOperations,
   type OcfCreateArguments,
-  type OcfCreateData,
-  type OcfCreateDataFor,
   type OcfCreateOperation,
   type OcfDataTypeFor,
   type OcfDeletableEntityType,
-  type OcfDeleteData,
-  type OcfDeleteDataFor,
   type OcfDeleteOperation,
   type OcfEditArguments,
-  type OcfEditData,
-  type OcfEditDataFor,
   type OcfEditOperation,
   type OcfEntityType,
-  type UpdateCapTableResult,
-} from './batchTypes';
-import { convertOperationToDaml, convertToDaml } from './ocfToDaml';
+} from './entityTypes';
+import {
+  buildOcfCreateData,
+  buildOcfCreateDataFromOperation,
+  buildOcfDeleteData,
+  buildOcfEditData,
+  buildOcfEditDataFromOperation,
+} from './generatedBatchOperations';
 
 /** Parameters for initializing a batch update. */
 export interface CapTableBatchParams extends CommandObservabilityOptions {
@@ -71,108 +68,6 @@ export interface BatchItemMeta {
   securityId?: string;
 }
 
-function decodeGeneratedOperation<T>(
-  decoder: { runWithException: (input: unknown) => T },
-  input: unknown,
-  operation: 'create' | 'edit' | 'delete',
-  entityType: OcfEntityType
-): T {
-  try {
-    return decoder.runWithException(input);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new OcpValidationError(
-      `batch.${operation}.${entityType}`,
-      `Converter output does not match the generated DAML ${operation} variant: ${message}`,
-      {
-        code: OcpErrorCodes.INVALID_FORMAT,
-        context: { operation, entityType },
-      }
-    );
-  }
-}
-
-function buildOcfCreateDataWith(type: OcfEntityType, convert: () => unknown): OcfCreateData {
-  if (!isOcfCreatableEntityType(type)) {
-    throw new OcpValidationError('type', `Create operation not supported for entity type: ${String(type)}`, {
-      code: OcpErrorCodes.INVALID_TYPE,
-    });
-  }
-
-  const tag = ENTITY_TAG_MAP[type].create;
-  return decodeGeneratedOperation(
-    Fairmint.OpenCapTable.CapTable.OcfCreateData.decoder,
-    { tag, value: convert() },
-    'create',
-    type
-  );
-}
-
-/** Build and validate one generated DAML create variant from a correlated entity-kind/data pair. */
-export function buildOcfCreateData<const Arguments extends OcfCreateArguments>(
-  ...args: Arguments
-): OcfCreateDataFor<Arguments[0]>;
-export function buildOcfCreateData(...args: OcfCreateArguments): OcfCreateData {
-  const [type] = args;
-  return buildOcfCreateDataWith(type, () => convertToDaml(...args));
-}
-
-function buildOcfCreateDataFromOperation(operation: OcfCreateOperation): OcfCreateData {
-  const { type } = operation;
-  return buildOcfCreateDataWith(type, () => convertOperationToDaml(operation));
-}
-
-function buildOcfEditDataWith(type: OcfEntityType, convert: () => unknown): OcfEditData {
-  if (!isOcfEditableEntityType(type)) {
-    throw new OcpValidationError('type', `Edit operation not supported for entity type: ${String(type)}`, {
-      code: OcpErrorCodes.INVALID_TYPE,
-    });
-  }
-
-  const tag = ENTITY_TAG_MAP[type].edit;
-  return decodeGeneratedOperation(
-    Fairmint.OpenCapTable.CapTable.OcfEditData.decoder,
-    { tag, value: convert() },
-    'edit',
-    type
-  );
-}
-
-/** Build and validate one generated DAML edit variant from a correlated entity-kind/data pair. */
-export function buildOcfEditData<const Arguments extends OcfEditArguments>(
-  ...args: Arguments
-): OcfEditDataFor<Arguments[0]>;
-export function buildOcfEditData(...args: OcfEditArguments): OcfEditData {
-  const [type] = args;
-  return buildOcfEditDataWith(type, () => convertToDaml(...args));
-}
-
-function buildOcfEditDataFromOperation(operation: OcfEditOperation): OcfEditData {
-  const { type } = operation;
-  return buildOcfEditDataWith(type, () => convertOperationToDaml(operation));
-}
-
-/** Build and validate one generated DAML delete variant. */
-export function buildOcfDeleteData<const EntityType extends OcfDeletableEntityType>(
-  type: EntityType,
-  id: string
-): OcfDeleteDataFor<EntityType>;
-export function buildOcfDeleteData(type: OcfDeletableEntityType, id: string): OcfDeleteData {
-  if (!isOcfDeletableEntityType(type)) {
-    throw new OcpValidationError('type', `Delete operation not supported for entity type: ${String(type)}`, {
-      code: OcpErrorCodes.INVALID_TYPE,
-    });
-  }
-
-  const tag = ENTITY_TAG_MAP[type].delete;
-  return decodeGeneratedOperation(
-    Fairmint.OpenCapTable.CapTable.OcfDeleteData.decoder,
-    { tag, value: id },
-    'delete',
-    type
-  );
-}
-
 /**
  * Fluent batch builder for cap table updates.
  *

src/functions/OpenCapTable/capTable/archiveCapTable.ts

@@ -11,7 +11,7 @@
 import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk/build/src/clients/ledger-json-api';
 import { OcpErrorCodes, OcpValidationError } from '../../../errors';
 import { submitObservedTransactionTree, type CommandObservabilityOptions } from '../../../observability';
-import type { CommandWithDisclosedContracts } from '../../../types';
+import type { CommandWithDisclosedContracts } from '../../../types/common';
 import { buildCapTableCommand } from './buildCapTableCommand';
 
 /** Parameters for archiving a CapTable contract. */

src/functions/OpenCapTable/capTable/archiveFullCapTable.ts

@@ -17,8 +17,8 @@ import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk/build/src/cl
 import { OcpErrorCodes } from '../../../errors/codes';
 import { OcpContractError } from '../../../errors/OcpContractError';
 import { archiveCapTable } from './archiveCapTable';
-import type { OcfEntityType } from './batchTypes';
 import { CapTableBatch } from './CapTableBatch';
+import type { OcfEntityType } from './entityTypes';
 import { classifyIssuerCapTables, type CapTableWithArchiveContext } from './getCapTableState';
 
 /** Minimal contract state needed for the archive operation. */