@fairmint/open-captable-protocol-daml-js 0.2.154 → 0.2.158

package/lib/index.d.ts

@@ -12,3 +12,10 @@ export declare const OCP_TEMPLATES: {
   readonly issuerAuthorization: typeof Fairmint_OpenCapTable_IssuerAuthorization.IssuerAuthorization.templateId;
   readonly ocpFactory: typeof Fairmint_OpenCapTable_OcpFactory.OcpFactory.templateId;
 };
+export {
+  getOpenCapTableDarPath,
+  resolveOpenCapTableDarPath,
+  OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH,
+  OPEN_CAP_TABLE_DAR_PATH_ENV,
+} from './openCapTableDarPath';
+export type { ResolveOpenCapTableDarPathOptions } from './openCapTableDarPath';

package/lib/index.js

@@ -23,3 +23,8 @@ exports.OCP_TEMPLATES = Object.freeze({
     issuerAuthorization: Fairmint_OpenCapTable_IssuerAuthorization.IssuerAuthorization.templateId,
     ocpFactory: Fairmint_OpenCapTable_OcpFactory.OcpFactory.templateId,
 });
+var _openCapTableDarPath = require('./openCapTableDarPath');
+exports.getOpenCapTableDarPath = _openCapTableDarPath.getOpenCapTableDarPath;
+exports.resolveOpenCapTableDarPath = _openCapTableDarPath.resolveOpenCapTableDarPath;
+exports.OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH = _openCapTableDarPath.OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH;
+exports.OPEN_CAP_TABLE_DAR_PATH_ENV = _openCapTableDarPath.OPEN_CAP_TABLE_DAR_PATH_ENV;

package/lib/openCapTableDarPath.d.ts

@@ -1,19 +1,46 @@
 /**
- * Absolute path to the OpenCapTable DAR shipped in this package (`published-dars/OpenCapTable.dar`).
+ * OpenCapTable DAR path helpers. Published as `@fairmint/open-captable-protocol-daml-js/openCapTableDarPath` (and
+ * re-exported from the package root).
  *
- * Published as `@fairmint/open-captable-protocol-daml-js/openCapTableDarPath` so tools and tests do not duplicate
- * `createRequire` / subpath strings.
+ * @remarks
+ *   User-facing documentation for `OPEN_CAP_TABLE_DAR_PATH`, monorepo layout, and options lives in this repository’s
+ *   **GitHub Wiki** — not in markdown files inside the repo.
  */
+/** Env var: absolute or cwd-relative path to a `.dar` file; checked first when set. */
+export declare const OPEN_CAP_TABLE_DAR_PATH_ENV: "OPEN_CAP_TABLE_DAR_PATH";
 /**
  * Npm `exports` subpath for the raw DAR file (for tools that need `require.resolve` / bundler parity).
  *
  * @see package.json `exports["./opencaptable.dar"]`
  */
 export declare const OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH: "./opencaptable.dar";
+export interface ResolveOpenCapTableDarPathOptions {
+    /**
+     * Root of the consuming repository (e.g. SDK or app checkout). The parent directory should contain
+     * `open-captable-protocol-daml` when using the default sibling layout.
+     */
+    siblingSearchFrom?: string;
+    /**
+     * Custom DAR path: absolute, or relative to `siblingSearchFrom` (required when relative). Use when the daml checkout
+     * is not at the default sibling path.
+     */
+    siblingDarPath?: string;
+}
 /**
- * Return the absolute path to the staged OpenCapTable DAR on disk.
+ * Absolute path to the OpenCapTable DAR inside this npm package (`published-dars/OpenCapTable.dar`).
  *
- * @throws If the file is missing (corrupt install or pre-staging checkout without `npm run codegen`).
+ * @throws If the file is missing (corrupt install, or git checkout without `npm run codegen` / staging).
  */
 export declare function getOpenCapTableDarPath(): string;
+/**
+ * Resolve the OpenCapTable DAR for local tooling and tests. Resolution order:
+ *
+ * 1. **`OPEN_CAP_TABLE_DAR_PATH`** (if set and the file exists).
+ * 2. Packaged DAR via {@link getOpenCapTableDarPath}.
+ * 3. **`siblingDarPath`** when it resolves to an existing file (absolute, or relative to `siblingSearchFrom`).
+ * 4. Default sibling checkout: `{siblingSearchFrom}/../open-captable-protocol-daml/published-dars/OpenCapTable.dar`.
+ *
+ * On failure after step 2, the thrown error sets **`cause`** to the packaged-DAR error when it was an `Error`.
+ */
+export declare function resolveOpenCapTableDarPath(options?: ResolveOpenCapTableDarPathOptions): string;
 //# sourceMappingURL=openCapTableDarPath.d.ts.map

package/lib/openCapTableDarPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openCapTableDarPath.d.ts","sourceRoot":"","sources":["../scripts/npm-published-lib/openCapTableDarPath.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAG,oBAA6B,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C"}
+{"version":3,"file":"openCapTableDarPath.d.ts","sourceRoot":"","sources":["../scripts/npm-published-lib/openCapTableDarPath.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAG,oBAA6B,CAAC;AAa/E,MAAM,WAAW,iCAAiC;IAChD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAqCD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,iCAAiC,GAAG,MAAM,CAmD9F"}

package/lib/openCapTableDarPath.js

@@ -1,9 +1,11 @@
 "use strict";
 /**
- * Absolute path to the OpenCapTable DAR shipped in this package (`published-dars/OpenCapTable.dar`).
+ * OpenCapTable DAR path helpers. Published as `@fairmint/open-captable-protocol-daml-js/openCapTableDarPath` (and
+ * re-exported from the package root).
  *
- * Published as `@fairmint/open-captable-protocol-daml-js/openCapTableDarPath` so tools and tests do not duplicate
- * `createRequire` / subpath strings.
+ * @remarks
+ *   User-facing documentation for `OPEN_CAP_TABLE_DAR_PATH`, monorepo layout, and options lives in this repository’s
+ *   **GitHub Wiki** — not in markdown files inside the repo.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -39,10 +41,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH = void 0;
+exports.OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH = exports.OPEN_CAP_TABLE_DAR_PATH_ENV = void 0;
 exports.getOpenCapTableDarPath = getOpenCapTableDarPath;
+exports.resolveOpenCapTableDarPath = resolveOpenCapTableDarPath;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/** Env var: absolute or cwd-relative path to a `.dar` file; checked first when set. */
+exports.OPEN_CAP_TABLE_DAR_PATH_ENV = 'OPEN_CAP_TABLE_DAR_PATH';
 /**
  * Npm `exports` subpath for the raw DAR file (for tools that need `require.resolve` / bundler parity).
  *
@@ -50,9 +55,49 @@ const path = __importStar(require("path"));
  */
 exports.OPEN_CAP_TABLE_DAR_EXPORT_SUBPATH = './opencaptable.dar';
 /**
- * Return the absolute path to the staged OpenCapTable DAR on disk.
+ * From a dependent repo root: sibling `open-captable-protocol-daml` staged DAR
+ * (`../open-captable-protocol-daml/published-dars/OpenCapTable.dar`).
+ */
+const DEFAULT_SIBLING_DAR_SEGMENTS = [
+    '..',
+    'open-captable-protocol-daml',
+    'published-dars',
+    'OpenCapTable.dar',
+];
+function readEnvDarPath() {
+    const raw = process.env[exports.OPEN_CAP_TABLE_DAR_PATH_ENV]?.trim();
+    if (!raw) {
+        return null;
+    }
+    const resolved = path.isAbsolute(raw) ? raw : path.resolve(process.cwd(), raw);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`${exports.OPEN_CAP_TABLE_DAR_PATH_ENV} points to a missing file: ${resolved} (raw: ${JSON.stringify(raw)})`);
+    }
+    return resolved;
+}
+function resolveCustomSiblingDar(options) {
+    const custom = options.siblingDarPath?.trim();
+    if (!custom) {
+        return null;
+    }
+    if (path.isAbsolute(custom)) {
+        return fs.existsSync(custom) ? custom : null;
+    }
+    const from = options.siblingSearchFrom?.trim();
+    if (!from) {
+        return null;
+    }
+    const joined = path.resolve(from, custom);
+    return fs.existsSync(joined) ? joined : null;
+}
+function defaultSiblingDar(siblingSearchFrom) {
+    const dar = path.join(siblingSearchFrom, ...DEFAULT_SIBLING_DAR_SEGMENTS);
+    return fs.existsSync(dar) ? dar : null;
+}
+/**
+ * Absolute path to the OpenCapTable DAR inside this npm package (`published-dars/OpenCapTable.dar`).
  *
- * @throws If the file is missing (corrupt install or pre-staging checkout without `npm run codegen`).
+ * @throws If the file is missing (corrupt install, or git checkout without `npm run codegen` / staging).
  */
 function getOpenCapTableDarPath() {
     const darPath = path.join(__dirname, '..', 'published-dars', 'OpenCapTable.dar');
@@ -62,4 +107,59 @@ function getOpenCapTableDarPath() {
     }
     return darPath;
 }
+/**
+ * Resolve the OpenCapTable DAR for local tooling and tests. Resolution order:
+ *
+ * 1. **`OPEN_CAP_TABLE_DAR_PATH`** (if set and the file exists).
+ * 2. Packaged DAR via {@link getOpenCapTableDarPath}.
+ * 3. **`siblingDarPath`** when it resolves to an existing file (absolute, or relative to `siblingSearchFrom`).
+ * 4. Default sibling checkout: `{siblingSearchFrom}/../open-captable-protocol-daml/published-dars/OpenCapTable.dar`.
+ *
+ * On failure after step 2, the thrown error sets **`cause`** to the packaged-DAR error when it was an `Error`.
+ */
+function resolveOpenCapTableDarPath(options) {
+    const opts = options ?? {};
+    const customRaw = opts.siblingDarPath?.trim();
+    if (customRaw && !path.isAbsolute(customRaw) && !opts.siblingSearchFrom?.trim()) {
+        throw new Error('resolveOpenCapTableDarPath: siblingDarPath is relative; set siblingSearchFrom to the dependent repository root.');
+    }
+    const envPath = readEnvDarPath();
+    if (envPath) {
+        return envPath;
+    }
+    try {
+        return getOpenCapTableDarPath();
+    }
+    catch (packagedCause) {
+        const custom = resolveCustomSiblingDar(opts);
+        if (custom) {
+            return custom;
+        }
+        const from = opts.siblingSearchFrom?.trim();
+        if (from) {
+            const siblingDar = defaultSiblingDar(from);
+            if (siblingDar) {
+                return siblingDar;
+            }
+        }
+        const base = packagedCause instanceof Error ? packagedCause.message : String(packagedCause);
+        const hints = [];
+        if (opts.siblingDarPath?.trim()) {
+            hints.push('siblingDarPath did not resolve to an existing file.');
+        }
+        if (from) {
+            hints.push('No DAR at ../open-captable-protocol-daml/published-dars/OpenCapTable.dar.');
+        }
+        else {
+            hints.push('Tip: set OPEN_CAP_TABLE_DAR_PATH, or pass siblingSearchFrom / siblingDarPath for monorepo dev (see GitHub Wiki).');
+        }
+        const msg = [base, hints.length ? ` ${hints.join(' ')}` : ''].join('');
+        if (packagedCause instanceof Error) {
+            const err = new Error(msg);
+            err.cause = packagedCause;
+            throw err;
+        }
+        throw new Error(msg);
+    }
+}
 //# sourceMappingURL=openCapTableDarPath.js.map

package/lib/openCapTableDarPath.js.map

@@ -1 +1 @@
-{"version":3,"file":"openCapTableDarPath.js","sourceRoot":"","sources":["../scripts/npm-published-lib/openCapTableDarPath.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBH,wDASC;AAxBD,uCAAyB;AACzB,2CAA6B;AAE7B;;;;GAIG;AACU,QAAA,iCAAiC,GAAG,oBAA6B,CAAC;AAE/E;;;;GAIG;AACH,SAAgB,sBAAsB;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;IACjF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,IAAI;YAC1C,yGAAyG,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"openCapTableDarPath.js","sourceRoot":"","sources":["../scripts/npm-published-lib/openCapTableDarPath.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairmint/open-captable-protocol-daml-js",
-  "version": "0.2.154",
+  "version": "0.2.158",
   "description": "Open CapTable Protocol DAML smart contracts with generated JavaScript bindings.",
   "keywords": [
     "daml",