Curate strict public SDK declarations#412
Conversation
# Conflicts: # src/functions/OpenCapTable/capTable/CapTableBatch.ts
# Conflicts: # test/declarations/publicApi.types.ts
|
Note Reviews pausedUse the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe package now exposes a curated root API with explicit Node entrypoints, introduces canonical cap-table entity and batch types, separates generated operation builders, adds issuer API types, decouples conversion declarations from generated DAML types, and strengthens declaration validation. ChangesSDK boundary and type-safe APIs
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
|
CI is green on the latest head, including the full OCP QuickStart integration suite. @copilot review |
|
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Pull request overview
This PR replaces the previous “wildcard” SDK surface with a curated, root-only public API, while moving generated DAML wiring (codecs, unions, low-level converters/readers) behind internal modules and enforcing the boundary via package.json exports and stricter declaration validation.
Changes:
- Curate
src/index.tsto export only high-level runtime APIs plus canonical OCF DTOs (and block package deep imports viapackage.json#exports). - Split public OCF-native batch/entity types into
entityTypes.ts, and move generated DAML operation builders intogeneratedBatchOperations.ts. - Tighten declaration validation (
check-declarations.ts) and add tests that lock down the root runtime export list and root declaration surface.
Reviewed changes
Copilot reviewed 38 out of 38 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/types/normalization.types.ts | Updates compile-time source contracts to import canonicalization helpers from their new internal module. |
| test/types/generatedOperationConstruction.types.ts | Repoints source type contracts to generated batch operation builders and internal batch types. |
| test/types/damlReadDispatch.types.ts | Adjusts source type contracts to import read-dispatch types from the cap-table facade + native types. |
| test/types/capTableBatch.types.ts | Updates source type contracts for batch API surface and new OcfContractId / execute result typing. |
| test/publicApi/rootExports.test.ts | Adds a runtime test that locks the curated root export key list. |
| test/integration/utils/setupTestData.ts | Minor type tightening (ReadonlyArray) for created CID extraction helper. |
| test/declarations/publicApi.types.ts | Updates built-SDK declaration smoke tests to match the curated root surface and removed exports. |
| test/declarations/normalization.types.ts | Updates built declaration contracts for canonicalization helpers to new module path. |
| test/declarations/generatedOperationConstruction.types.ts | Repoints built declaration contracts to generated batch operation builders and internal batch types. |
| test/declarations/damlReadDispatch.types.ts | Repoints built declaration contracts to internal read-dispatch modules/types. |
| test/converters/coreObjectReadValidation.test.ts | Updates imports to avoid relying on root re-exports for internal converter helpers. |
| test/client/OcpClient.test.ts | Updates spying/import paths for cap-table state helpers after refactor. |
| test/batch/generatedOperationConstruction.test.ts | Repoints batch tests to new generated operation builders + internal registry/tag map modules. |
| test/batch/batchTypes.test.ts | Repoints registry import to new internal batchTypes module. |
| src/types/index.ts | Removes DAML barrel export and moves CommandWithDisclosedContracts out of this index barrel. |
| src/types/common.ts | Adds CommandWithDisclosedContracts to the common type module used by high-level APIs. |
| src/OcpClient.ts | Refactors imports to new cap-table/issuer/authorization modules and aliases CapTableUpdateParams. |
| src/index.ts | Implements curated root public API exports (no more wildcard re-export of functions/types/utils). |
| src/functions/OpenCapTable/stockIssuance/createStockIssuance.ts | Splits native vs DAML type imports to keep public/native surface clean. |
| src/functions/OpenCapTable/issuerAuthorization/withdrawAuthorization.ts | Moves public param/result types to a dedicated types module and re-exports them. |
| src/functions/OpenCapTable/issuerAuthorization/types.ts | Introduces shared public issuer-authorization params/results module. |
| src/functions/OpenCapTable/issuerAuthorization/index.ts | Re-exports new issuer-authorization types. |
| src/functions/OpenCapTable/issuerAuthorization/authorizeIssuer.ts | Moves public param/result types to the new types module and re-exports them. |
| src/functions/OpenCapTable/issuer/types.ts | Introduces issuer CreateCapTable input/params types behind a dedicated module. |
| src/functions/OpenCapTable/issuer/index.ts | Switches issuer public export surface to the new API facade while keeping internal helpers. |
| src/functions/OpenCapTable/issuer/createIssuer.ts | Moves public types out to types.ts and updates imports to common/native types. |
| src/functions/OpenCapTable/issuer/api.ts | Adds a public wrapper for CreateIssuer command builder isolated from generated converter declarations. |
| src/functions/OpenCapTable/capTable/index.ts | Re-exports generated operation builders from the new module and adjusts cap-table exports. |
| src/functions/OpenCapTable/capTable/getCapTableState.ts | Adjusts imports to avoid leaking entity type definitions from the generated batchTypes module. |
| src/functions/OpenCapTable/capTable/generatedBatchOperations.ts | New module that builds/validates generated DAML create/edit/delete variants via decoders. |
| src/functions/OpenCapTable/capTable/entityTypes.ts | New module defining public OCF-native entity unions, guards, and batch result/contract-id typing. |
| src/functions/OpenCapTable/capTable/CapTableBatch.ts | Refactors batch builder to delegate generated wire construction to generatedBatchOperations. |
| src/functions/OpenCapTable/capTable/buildCapTableCommand.ts | Updates CommandWithDisclosedContracts import to the new common type module. |
| src/functions/OpenCapTable/capTable/batchTypes.ts | Refactors to re-export public OCF types from entityTypes and keep generated DAML types local. |
| src/functions/OpenCapTable/capTable/archiveFullCapTable.ts | Updates entity type import to the new entityTypes module. |
| src/functions/OpenCapTable/capTable/archiveCapTable.ts | Updates CommandWithDisclosedContracts import to the new common type module. |
| scripts/check-declarations.ts | Tightens declaration validation by typechecking a strict consumer and checking for generated DAML package leaks in the root declaration graph. |
| package.json | Adds a root-only exports map to block unsupported deep imports and enforce the curated public surface. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Final parent-fix propagation complete at exact head |
Reviewed the exact current head ( |
|
@cursor review Please review exact head f625fbb. Copilot completed an explicit exact-head no-findings review: #412 (comment). Current gate remains green: both required checks SUCCESS, CLEAN/MERGEABLE, unassigned, and zero unresolved review threads. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit f625fbb. Configure here.
|
@coderabbitai review Please perform a substantive incremental review of exact current head f625fbb, including the final propagated parent-fix delta since the prior substantive CodeRabbit review. Copilot completed an exact-head no-findings review: #412 (comment). Cursor completed an exact-head no-findings formal review: #412 (review). Please run the real analysis phases and submit a formal exact-head review; an instant status check is not sufficient. |
|
✅ Action performedReview finished.
|
|
@coderabbitai review Please perform a substantive incremental review of exact current head |
|
✅ Action performedReview finished.
|
|
Readiness temporarily retracted: upstream #411 does not yet contain the current exact head of its own base #409. This PR is back in draft and unassigned until #411 is repaired, its corrected exact head is merged normally into this branch, validation is green, and Copilot plus the other enabled review agents complete fresh exact-head passes. |
|
Pivot cleanup is now on exact head |
|
@copilot review Please review exact head |
Reviewed the exact head ( |
|
@cursor review Please review exact head |
|
@coderabbitai review Please perform a substantive review of exact head |
|
✅ Action performedReview finished.
|
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a28dfb8. Configure here.
| import type { CommandWithDisclosedContracts } from '../../../types/common'; | ||
| import { type OcfCreateData, type OcfDeleteData, type OcfEditData, type UpdateCapTableResult } from './batchTypes'; | ||
| import { |
| TX_WARRANT_TRANSFER: 'warrantTransfer', | ||
| VALUATION: 'valuation', | ||
| VESTING_TERMS: 'vestingTerms', | ||
| } as const satisfies Record<string, OcfEntityType>); |
Summary
mainv0.8.0DAML / SDK boundary
DAML remains authoritative for domain correctness and integrity. This PR does not reintroduce #411 date, graph, pricing, quantity, cardinality, or cross-field semantic preflight. The SDK checks retained here are operation-capability, template identity, and generated-codec/JSON transport checks needed to construct or decode the wire value faithfully.
Validation on exact final tree
npm run buildnpm run test:declarationswithskipLibCheck: falseand no generated DAML packages reachable from the root declaration graphnpm run typechecknpm test -- --runInBand— 61 suites / 2,773 tests passednpm run lintnpm run formatgit diff --checkRevision note
The final tree was rebuilt from current
main(v0.8.0) and attached to this existing branch with an additive merge commit. No history was rewritten or force-pushed. The PR remains draft until exact-head CI is green and fresh automated review completes.Note
Medium Risk
Broad export and type-surface change can break downstream imports that relied on deep or generated symbols; runtime behavior is mostly refactored behind the same client/batch flows.
Overview
Replaces wildcard root exports with a curated high-level surface (
OcpClient, batch helpers, issuer auth, environment/errors/types) and adds an explicitpackage.jsonexportsmap for the package root only.Splits public types from generated DAML wiring: new
entityTypesholds canonical OCF-native batch/entity/result types (includingOcfContractIdand a frozenOCF_OBJECT_TYPE_TO_ENTITY_TYPEmap); DAML decode/build logic moves togeneratedBatchOperationsand stays off the root graph. Issuer and issuer-authorization params/results live in thinapi/typesmodules that route ledger response types throughtypes/common.Tightens declaration checks:
check-declarationsvalidates a strict consumer fixture, fails ifdistreferences@fairmint/open-captable-protocol-daml-js, and enforces transaction-tree types viacommon. Tests lock the runtime export list and compile-time contracts so converters/registry helpers are not root exports.Reviewed by Cursor Bugbot for commit a28dfb8. Bugbot is set up for automated code reviews on this repo. Configure here.