@c7-digital/ledger 0.0.2

package/BUILD.md

@@ -0,0 +1,125 @@
+# Ledger Build
+
+A standalone, repeatable build system for generating TypeScript types from OpenAPI and AsyncAPI specifications with value.proto branding.
+
+## Features
+
+- **SDK Version Targeting**: Generate types for specific Daml SDK versions
+- **Auto-Discovery**: Automatically find the latest specification files
+- **In-Place Branding**: Apply value.proto constraints to generated types
+- **Parallel Processing**: Optimize build performance with concurrent operations
+- **Schema Embedding**: Include YAML schemas for runtime validation
+- **Portable**: No hardcoded paths, works as standalone package
+
+## Usage
+
+### As NPM Script
+
+```bash
+pnpm build                           # Use configured SDK version
+pnpm build -- --sdk-version=3.4.0   # Override SDK version
+```
+
+### As Standalone Binary
+
+```bash
+pnpm exec ledger-build                        # Auto-discover latest specs
+pnpm exec ledger-build --sdk-version=3.4.0    # Target specific SDK version
+```
+
+### Programmatic Usage
+
+```typescript
+import { build } from "@c7-digital/ledger/scripts/build";
+
+await build();
+```
+
+## Required Dependencies
+
+The build system requires these development dependencies:
+
+```json
+{
+  "devDependencies": {
+    "openapi-typescript": "^7.4.2",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.11.0",
+    "typescript": "^5.8.3",
+    "yaml": "^2.8.1"
+  }
+}
+```
+
+## Directory Structure
+
+### Input
+
+```
+specs/
+├── openapi_{SDK_VERSION}.yaml
+└── asyncapi_{SDK_VERSION}.yaml
+```
+
+### Output
+
+```
+src/generated/
+├── api.ts              # OpenAPI types (branded)
+├── async-api.ts        # AsyncAPI types (branded)
+├── asyncapi-schema.ts  # Embedded AsyncAPI YAML
+├── openapi-schema.ts   # Embedded OpenAPI YAML
+└── sdk-version.ts      # SDK version constant
+```
+
+## Branding
+
+The build system automatically applies value.proto constraints to string fields:
+
+- `LedgerString` for contract/update/command IDs
+- `PartyIdString` for party identifiers
+- `UserIdString` for user identifiers
+- `NameString` for choice names
+- `PackageIdString` for template/package identifiers
+
+## Standalone Package Usage
+
+To use this build system in other projects:
+
+1. **Install the package**:
+
+   ```bash
+   pnpm install @c7-digital/ledger
+   ```
+
+2. **Add to package.json**:
+
+   ```json
+   {
+     "scripts": {
+       "generate-types": "pnpm exec ledger-build --sdk-version=3.4.0"
+     }
+   }
+   ```
+
+3. **Create spec directory structure**:
+
+   ```
+   specs/
+   ├── openapi_3.4.0.yaml
+   └── asyncapi_3.4.0.yaml
+   ```
+
+4. **Run the build**:
+   ```bash
+   pnpm run generate-types
+   ```
+
+## Environment Variables
+
+- `SDK_VERSION`: Default SDK version (overridden by --sdk-version)
+
+## Exit Codes
+
+- `0`: Success
+- `1`: Build failure (missing specs, compilation errors, etc.

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright [2025] [C7.digital]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,97 @@
+# @c7-digital/ledger
+
+OpenAPI v2 compatible Daml ledger client (that could replace `@daml/ledger`) for the new Canton JSON API v2.
+
+## Overview
+
+This package provides a TypeScript client for interacting with Canton's JSON Ledger API v2, which replaces the deprecated v1 API that `@daml/ledger` targets.
+
+## Features
+
+- **Type-safe API**: Generated TypeScript types from OpenAPI specification
+- **OpenAPI v2 Support**: Targets the new Canton JSON API v2 endpoints
+- **Auto-generated Types**: Uses `openapi-typescript` to generate accurate type definitions
+
+## Versioning
+
+This package follows the Canton SDK versioning scheme. The package version matches the Canton OpenAPI specification version used to generate the types.
+
+**Current version**: `3.4.7`
+
+- Corresponds to Canton SDK version `3.4.7`
+- Types are generated from the OpenAPI spec for this specific Canton version
+- When Canton releases a new version, this package will be updated to match
+
+**Version compatibility**: Use the package version that matches your Canton participant node version for best compatibility.
+
+## Installation
+
+```bash
+pnpm install @c7-digital/ledger
+```
+
+Or build from source:
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Usage
+
+```typescript
+import { Ledger } from "@c7-digital/ledger";
+
+const ledger = new Ledger({
+  token: "your-jwt-token",
+  httpBaseUrl: "http://localhost:7575",
+});
+
+// Query contracts
+const contracts = await ledger.query(MyTemplate);
+
+// Create contracts
+const result = await ledger.create(MyTemplate, payload, [actAsParty]);
+
+// Exercise choices
+const choiceResult = await ledger.exercise(MyChoice, contractId, argument, [
+  actAsParty,
+]);
+```
+
+## Migration from @daml/ledger
+
+Key differences:
+
+- `create()` and `exercise()` methods now require an `actAs` parameter
+- Some method signatures have been updated to match OpenAPI v2 spec
+- New type definitions generated from OpenAPI specification
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Clean build artifacts
+pnpm clean
+
+# Watch for changes
+pnpm watch
+
+# Run tests
+pnpm test
+
+# Lint code
+pnpm lint
+```
+
+## OpenAPI Specification
+
+The package uses the OpenAPI specification from Canton 3.4.7. The spec is saved as a version specific file (e.x. `openapi_3.4.7.yaml`) and types are automatically generated into `src/generated/api.ts`.
+
+To update the specification:
+
+1. Download from docs.digitalasset.com or from your participant node.
+2. Update the build script to use the new SDK version
+3. Run `pnpm build` to regenerate types

package/lib/scripts/build.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env tsx
+/**
+ * Unified build script that uses SDK version-based spec files and runs all build steps
+ */
+/**
+ * Main build function - builds both regular and lite versions
+ */
+declare function build(): Promise<void>;
+export { build };

package/lib/scripts/build.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env tsx
+/**
+ * Unified build script that uses SDK version-based spec files and runs all build steps
+ */
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { readdir, writeFile, mkdir, unlink, copyFile } from "fs/promises";
+import { existsSync } from "fs";
+import { brandTypes } from "./enhance-types.js";
+import { generateSchemaModule } from "./generate-schema-modules.js";
+import { generateAsyncApiTypes } from "./generate-asyncapi-types.js";
+const execAsync = promisify(exec);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = join(__dirname, "..");
+/**
+ * Get SDK version from command line arguments or discover latest
+ */
+function getSdkVersion() {
+    const args = process.argv.slice(2);
+    const versionArg = args.find(arg => arg.startsWith("--sdk-version="));
+    if (versionArg) {
+        return versionArg.split("=")[1];
+    }
+    return undefined;
+}
+/**
+ * Discover spec files based on SDK version or find latest version-based specs
+ */
+async function discoverSpecFiles(sdkVersion) {
+    const specsDir = join(projectRoot, "specs");
+    const files = await readdir(specsDir);
+    if (sdkVersion) {
+        console.log(`🔍 Looking for spec files with SDK version: ${sdkVersion}`);
+        const openApiFile = `openapi_${sdkVersion}.yaml`;
+        const asyncApiFile = `asyncapi_${sdkVersion}.yaml`;
+        const result = {};
+        if (files.includes(openApiFile)) {
+            result.openapi = join(specsDir, openApiFile);
+            console.log(`📄 Found OpenAPI spec: ${openApiFile}`);
+        }
+        else {
+            console.warn(`⚠️  OpenAPI spec not found: ${openApiFile}`);
+        }
+        if (files.includes(asyncApiFile)) {
+            result.asyncapi = join(specsDir, asyncApiFile);
+            console.log(`📄 Found AsyncAPI spec: ${asyncApiFile}`);
+        }
+        else {
+            console.warn(`⚠️  AsyncAPI spec not found: ${asyncApiFile}`);
+        }
+        return { specs: result, version: sdkVersion };
+    }
+    else {
+        console.log("🔍 Auto-discovering latest version-based spec files...");
+        // Look for files with version pattern (not date pattern)
+        const versionPattern = /\d+\.\d+\.\d+(-snapshot\.\d{8}\.\d+)?/;
+        const openApiFiles = files
+            .filter(f => f.startsWith("openapi_") && f.endsWith(".yaml") && versionPattern.test(f))
+            .sort()
+            .reverse();
+        const asyncApiFiles = files
+            .filter(f => f.startsWith("asyncapi_") && f.endsWith(".yaml") && versionPattern.test(f))
+            .sort()
+            .reverse();
+        const result = {};
+        let detectedVersion = "";
+        if (openApiFiles.length > 0) {
+            result.openapi = join(specsDir, openApiFiles[0]);
+            console.log(`📄 Found OpenAPI spec: ${openApiFiles[0]}`);
+            // Extract version from filename
+            const match = openApiFiles[0].match(/openapi_(.+)\.yaml/);
+            if (match)
+                detectedVersion = match[1];
+        }
+        if (asyncApiFiles.length > 0) {
+            result.asyncapi = join(specsDir, asyncApiFiles[0]);
+            console.log(`📄 Found AsyncAPI spec: ${asyncApiFiles[0]}`);
+            // Use version from AsyncAPI if OpenAPI wasn't found
+            if (!detectedVersion) {
+                const match = asyncApiFiles[0].match(/asyncapi_(.+)\.yaml/);
+                if (match)
+                    detectedVersion = match[1];
+            }
+        }
+        if (!detectedVersion) {
+            throw new Error("Could not detect SDK version from spec files. Please specify --sdk-version=<version>");
+        }
+        console.log(`🎯 Detected SDK version: ${detectedVersion}`);
+        return { specs: result, version: detectedVersion };
+    }
+}
+/**
+ * Generate OpenAPI types using openapi-typescript
+ */
+async function generateTypes(specPath) {
+    console.log("🔄 Generating OpenAPI types...");
+    const outputPath = join(projectRoot, "src", "generated", "api.ts");
+    try {
+        const { stdout, stderr } = await execAsync(`pnpm exec openapi-typescript "${specPath}" --output "${outputPath}"`);
+        if (stderr && !stderr.includes("Warning")) {
+            console.warn("openapi-typescript warnings:", stderr);
+        }
+        if (stdout) {
+            console.log(stdout);
+        }
+        console.log("✅ Generated OpenAPI types");
+    }
+    catch (error) {
+        console.error("❌ Error generating OpenAPI types:", error.message);
+        throw error;
+    }
+}
+/**
+ * Generate schema modules for both OpenAPI and AsyncAPI
+ */
+function generateSchemaModules(specs) {
+    console.log("🔄 Generating schema modules...");
+    const outputDir = join(projectRoot, "src", "generated");
+    if (specs.openapi) {
+        generateSchemaModule(specs.openapi, join(outputDir, "openapi-schema.ts"), "OPENAPI_SCHEMA");
+    }
+    if (specs.asyncapi) {
+        generateSchemaModule(specs.asyncapi, join(outputDir, "asyncapi-schema.ts"), "ASYNCAPI_SCHEMA");
+    }
+    console.log("✅ All schema modules generated");
+}
+/**
+ * Ensure the generated directory exists
+ */
+async function ensureGeneratedDirectory() {
+    const outputDir = join(projectRoot, "src", "generated");
+    await mkdir(outputDir, { recursive: true });
+}
+/**
+ * Clean up any temporary files
+ */
+async function cleanupTempFiles() {
+    const generatedDir = join(projectRoot, "src", "generated");
+    const tempFiles = [
+        join(generatedDir, "api.ts.tmp"),
+        join(generatedDir, "async-api.ts.tmp"),
+        join(projectRoot, "temp-asyncapi-as-openapi.yaml"),
+    ];
+    for (const tempFile of tempFiles) {
+        if (existsSync(tempFile)) {
+            try {
+                await unlink(tempFile);
+                console.log(`🧹 Cleaned up ${tempFile}`);
+            }
+            catch (error) {
+                // Ignore cleanup errors, but log them
+                console.warn(`⚠️  Could not clean up ${tempFile}:`, error.message);
+            }
+        }
+    }
+}
+/**
+ * Generate SDK version constant file
+ */
+async function generateSdkVersionFile(version) {
+    console.log("🔄 Generating SDK version constant...");
+    const outputDir = join(projectRoot, "src", "generated");
+    const outputPath = join(outputDir, "sdk-version.ts");
+    const content = `// Auto-generated file - do not edit manually
+// Generated from SDK version: ${version}
+
+export const SDK_VERSION = "${version}";
+`;
+    await writeFile(outputPath, content, "utf-8");
+    console.log(`✅ Generated SDK version constant: ${version}`);
+}
+/**
+ * Brand API types with value.proto constraints (in-place)
+ */
+function brandApiTypes() {
+    console.log("🔄 Branding API types in-place...");
+    // Brand OpenAPI types (overwrite original file)
+    const apiPath = join(projectRoot, "src", "generated", "api.ts");
+    brandTypes(apiPath, apiPath, "OpenAPI");
+    // Brand AsyncAPI types (overwrite original file)
+    const asyncApiPath = join(projectRoot, "src", "generated", "async-api.ts");
+    brandTypes(asyncApiPath, asyncApiPath, "AsyncAPI");
+    console.log("✅ All types branded in-place");
+}
+/**
+ * Create stub schema files for lite build
+ */
+async function createStubSchemaFiles() {
+    console.log("🔄 Creating stub schema files for lite build...");
+    const outputDir = join(projectRoot, "src", "generated");
+    const openApiStub = `// Stub file for lite build - no schema content
+export const OPENAPI_SCHEMA = "";
+`;
+    const asyncApiStub = `// Stub file for lite build - no schema content
+export const ASYNCAPI_SCHEMA = "";
+`;
+    await writeFile(join(outputDir, "openapi-schema.ts"), openApiStub, "utf-8");
+    await writeFile(join(outputDir, "asyncapi-schema.ts"), asyncApiStub, "utf-8");
+    console.log("✅ Created stub schema files");
+}
+/**
+ * Replace validation module with lite version in lib-lite
+ */
+async function useLiteValidation() {
+    console.log("🔄 Replacing validation with lite version...");
+    const libLiteDir = join(projectRoot, "lib-lite", "src");
+    // Copy validation-lite.js over validation.js
+    const liteValidationJs = join(libLiteDir, "validation-lite.js");
+    const validationJs = join(libLiteDir, "validation.js");
+    if (existsSync(liteValidationJs)) {
+        await copyFile(liteValidationJs, validationJs);
+        await unlink(liteValidationJs);
+        console.log("✅ Replaced validation.js with lite version");
+    }
+    // Copy validation-lite.d.ts over validation.d.ts
+    const liteValidationDts = join(libLiteDir, "validation-lite.d.ts");
+    const validationDts = join(libLiteDir, "validation.d.ts");
+    if (existsSync(liteValidationDts)) {
+        await copyFile(liteValidationDts, validationDts);
+        await unlink(liteValidationDts);
+        console.log("✅ Replaced validation.d.ts with lite version");
+    }
+    // Also remove validation-lite files from lib/ (they shouldn't be there)
+    const libDir = join(projectRoot, "lib", "src");
+    const libLiteValidationJs = join(libDir, "validation-lite.js");
+    const libLiteValidationDts = join(libDir, "validation-lite.d.ts");
+    if (existsSync(libLiteValidationJs)) {
+        await unlink(libLiteValidationJs);
+    }
+    if (existsSync(libLiteValidationDts)) {
+        await unlink(libLiteValidationDts);
+    }
+}
+/**
+ * Compile TypeScript code
+ */
+async function compileTypeScript(outDir = "lib") {
+    console.log(`🔄 Compiling TypeScript to ${outDir}...`);
+    try {
+        let tscCommand = `pnpm exec tsc -p ${join(projectRoot, "tsconfig.json")}`;
+        let aliasCommand = `pnpm exec tsc-alias -p ${join(projectRoot, "tsconfig.json")}`;
+        if (outDir !== "lib") {
+            // Create a temporary tsconfig for different output directory
+            const tempTsConfig = {
+                extends: "./tsconfig.json",
+                compilerOptions: {
+                    outDir: `./${outDir}`,
+                    declarationDir: `./${outDir}`,
+                },
+            };
+            const tempConfigPath = join(projectRoot, "tsconfig.temp.json");
+            await writeFile(tempConfigPath, JSON.stringify(tempTsConfig, null, 2), "utf-8");
+            tscCommand = `pnpm exec tsc -p ${tempConfigPath}`;
+            aliasCommand = `pnpm exec tsc-alias -p ${tempConfigPath}`;
+        }
+        // Run tsc first (tsc-alias depends on tsc output)
+        const { stdout: tscStdout, stderr: tscStderr } = await execAsync(tscCommand);
+        if (tscStderr) {
+            console.error("TypeScript compiler errors/warnings:");
+            console.error(tscStderr);
+        }
+        if (tscStdout) {
+            console.log("TypeScript compiler output:");
+            console.log(tscStdout);
+        }
+        // Run tsc-alias after tsc completes
+        const { stdout: aliasStdout, stderr: aliasStderr } = await execAsync(aliasCommand);
+        if (aliasStderr) {
+            console.warn("tsc-alias warnings:", aliasStderr);
+        }
+        if (aliasStdout) {
+            console.log(aliasStdout);
+        }
+        // Clean up temp config if created
+        if (outDir !== "lib") {
+            const tempConfigPath = join(projectRoot, "tsconfig.temp.json");
+            if (existsSync(tempConfigPath)) {
+                await unlink(tempConfigPath);
+            }
+        }
+        console.log(`✅ TypeScript compilation complete for ${outDir}`);
+    }
+    catch (error) {
+        console.error(`❌ Error compiling TypeScript to ${outDir}:`);
+        console.error(error.message);
+        // If the error has stdout/stderr, display them
+        if (error && typeof error === "object" && "stdout" in error && error.stdout) {
+            console.error("TypeScript stdout:");
+            console.error(error.stdout);
+        }
+        if (error && typeof error === "object" && "stderr" in error && error.stderr) {
+            console.error("TypeScript stderr:");
+            console.error(error.stderr);
+        }
+        console.error("💡 Note: TypeScript compilation failed, but code generation was successful.");
+        console.error("💡 Check the errors above and fix any type issues in your source files.");
+        throw error;
+    }
+}
+/**
+ * Main build function - builds both regular and lite versions
+ */
+async function build() {
+    console.log("🚀 Starting SDK version-aware build process...");
+    try {
+        // Step 1: Get SDK version and discover spec files
+        const sdkVersion = getSdkVersion();
+        const { specs, version } = await discoverSpecFiles(sdkVersion);
+        if (!specs.openapi && !specs.asyncapi) {
+            throw new Error(`No spec files found for SDK version: ${version}`);
+        }
+        // Step 2: Ensure generated directory exists
+        await ensureGeneratedDirectory();
+        // Step 3: Generate SDK version constant (independent, can run early)
+        const sdkVersionPromise = generateSdkVersionFile(version);
+        // Step 4: Run type generation in parallel (all independent)
+        const parallelTasks = [];
+        if (specs.openapi) {
+            parallelTasks.push(generateTypes(specs.openapi));
+        }
+        if (specs.asyncapi) {
+            parallelTasks.push(generateAsyncApiTypes(specs.asyncapi));
+        }
+        // Wait for SDK version file and all parallel type generation
+        await Promise.all([sdkVersionPromise, ...parallelTasks]);
+        // Step 5: Brand types (depends on generated types)
+        brandApiTypes();
+        console.log("🎯 Building regular version with full schemas...");
+        // Step 6a: Generate full schema modules for regular build
+        generateSchemaModules(specs);
+        // Step 6b: Compile regular TypeScript (depends on all previous steps)
+        await compileTypeScript("lib");
+        console.log("🎯 Building lite version without schemas...");
+        // Step 7a: Create stub schema files for lite build
+        await createStubSchemaFiles();
+        // Step 7b: Compile lite TypeScript to separate directory
+        await compileTypeScript("lib-lite");
+        // Step 7c: Replace validation with lite version (no yaml dependency)
+        await useLiteValidation();
+        // Step 8: Clean up any temporary files
+        await cleanupTempFiles();
+        console.log(`🎉 Both regular and lite builds completed successfully for version: ${version}!`);
+        console.log(`📦 Regular build: lib/ (with validation schemas)`);
+        console.log(`📦 Lite build: lib-lite/ (without validation schemas)`);
+    }
+    catch (error) {
+        console.error("❌ Build failed:", error.message);
+        // Attempt cleanup even on failure
+        try {
+            await cleanupTempFiles();
+        }
+        catch (cleanupError) {
+            console.warn("⚠️  Could not clean up temp files after build failure");
+        }
+        process.exit(1);
+    }
+}
+// Run the build if this script is executed directly
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    build();
+}
+// Export for use in other scripts
+export { build };

package/lib/scripts/enhance-types.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+declare function brandTypes(inputPath: string, outputPath: string, label?: string): void;
+export { brandTypes };