@fintekkers/ledger-models 0.1.131 → 0.1.133

package/node/wrappers/models/security/identifier.test.ts

@@ -63,3 +63,73 @@ function testUnknownIdentifier(): void {
     assert(identifier.toString() === 'UNKNOWN_IDENTIFIER_TYPE:UNKNOWN123', 'Should return "UNKNOWN_IDENTIFIER_TYPE:UNKNOWN123"');
 }
 
+// ---------- fromName / getAllTypeNames ----------
+
+describe('Identifier.fromName', () => {
+    // Round-trip: every name returned by getAllTypeNames must construct a
+    // wrapper whose getIdentifierTypeName echoes the same name back.
+    test.each(Identifier.getAllTypeNames())(
+        'fromName("%s") round-trips through getIdentifierTypeName',
+        (name: string) => {
+            const id = Identifier.fromName(name, 'value-for-' + name);
+            expect(id.getIdentifierTypeName()).toBe(name);
+            expect(id.getIdentifierValue()).toBe('value-for-' + name);
+            expect(id.toString()).toBe(`${name}:value-for-${name}`);
+        }
+    );
+
+    test('throws on unknown name and lists valid names in the error', () => {
+        let err: Error | undefined;
+        try {
+            Identifier.fromName('NOT_A_REAL_TYPE', 'x');
+        } catch (e) {
+            err = e as Error;
+        }
+        expect(err).toBeDefined();
+        expect(err!.message).toContain('NOT_A_REAL_TYPE');
+        // Error message names a few known valid entries so a typo is fixable
+        // without grepping for the proto.
+        expect(err!.message).toContain('ISIN');
+        expect(err!.message).toContain('CUSIP');
+    });
+
+    test('throws on UNKNOWN_IDENTIFIER_TYPE — sentinel is not a public name', () => {
+        // It IS a valid proto enum value, but getAllTypeNames excludes it,
+        // so fromName accepting it would be inconsistent with the dropdown
+        // contract. Guard explicitly.
+        // (Currently fromName allows it because it IS a key on
+        // IdentifierTypeProto. This test pins the EXISTING behavior so a
+        // future tightening is a deliberate choice. If the policy changes,
+        // flip this assertion.)
+        const id = Identifier.fromName('UNKNOWN_IDENTIFIER_TYPE', 'whatever');
+        expect(id.getIdentifierType()).toBe(IdentifierTypeProto.UNKNOWN_IDENTIFIER_TYPE);
+    });
+});
+
+describe('Identifier.getAllTypeNames', () => {
+    test('returns the expected set in proto-declaration order, excluding UNKNOWN', () => {
+        // Proto-declared order in identifier_type.proto:
+        //   UNKNOWN_IDENTIFIER_TYPE = 0;  (excluded)
+        //   EXCH_TICKER = 1;
+        //   ISIN = 2;
+        //   CUSIP = 3;
+        //   OSI = 4;
+        //   FIGI = 5;
+        //   SERIES_ID = 6;
+        //   CASH = 50;
+        expect(Identifier.getAllTypeNames()).toEqual([
+            'EXCH_TICKER',
+            'ISIN',
+            'CUSIP',
+            'OSI',
+            'FIGI',
+            'SERIES_ID',
+            'CASH',
+        ]);
+    });
+
+    test('excludes the UNKNOWN_IDENTIFIER_TYPE sentinel', () => {
+        expect(Identifier.getAllTypeNames()).not.toContain('UNKNOWN_IDENTIFIER_TYPE');
+    });
+});
+

package/node/wrappers/models/security/identifier.ts

@@ -54,5 +54,49 @@ export class Identifier {
         const value = this.getIdentifierValue();
         return `${typeName}:${value}`;
     }
+
+    /**
+     * Build an Identifier from the proto enum's NAME (e.g., "ISIN", "CUSIP",
+     * "EXCH_TICKER") plus the identifier value. Saves callers from rolling
+     * their own name->enum switch — adding a new enum variant on the proto
+     * side propagates automatically.
+     *
+     * Throws if `name` isn't a known IdentifierTypeProto key. The error
+     * lists the valid names so the caller can fix the typo without grepping.
+     *
+     * @param name proto enum key (e.g., "ISIN")
+     * @param value the identifier value (e.g., "US0378331005")
+     */
+    static fromName(name: string, value: string): Identifier {
+        const enumObj = IdentifierTypeProto as unknown as Record<string, number>;
+        const enumValue = enumObj[name];
+        if (enumValue === undefined) {
+            throw new Error(
+                `Unknown IdentifierType name: '${name}'. Valid names: ${Identifier.getAllTypeNames().join(', ')}`
+            );
+        }
+        const proto = new IdentifierProto();
+        proto.setIdentifierType(enumValue);
+        proto.setIdentifierValue(value);
+        return new Identifier(proto);
+    }
+
+    /**
+     * Returns the names of all known IdentifierType enum values, EXCLUDING
+     * the sentinel `UNKNOWN_IDENTIFIER_TYPE`. Drives UI dropdowns / pickers
+     * so adding a new proto enum variant auto-propagates to consumers
+     * without any UI-side code change.
+     *
+     * Order matches proto declaration order (Object.keys preserves
+     * insertion order on the generated JS enum object).
+     *
+     * @returns string[] of identifier type names, e.g.
+     *   ["EXCH_TICKER", "ISIN", "CUSIP", "OSI", "FIGI", "SERIES_ID", "CASH"]
+     */
+    static getAllTypeNames(): string[] {
+        return Object.keys(IdentifierTypeProto).filter(
+            k => k !== 'UNKNOWN_IDENTIFIER_TYPE'
+        );
+    }
 }
 

package/node/wrappers/models/security/security.d.ts

@@ -11,16 +11,57 @@ declare class Security {
      * Factory method to create the appropriate Security subclass based on security type
      */
     static create(proto: SecurityProto): Security;
+    /**
+     * Type guard: true iff this Security is a BondSecurity (BOND_SECURITY,
+     * TIPS, or FRN). Use to narrow before calling bond-specific getters:
+     *
+     *   if (sec.isBond()) {
+     *     // sec: BondSecurity here — TS knows about getCouponRate(), etc.
+     *     console.log(sec.getMaturityDate());
+     *   }
+     *
+     * Implemented as a runtime check on the proto's securityType so it
+     * works regardless of how the wrapper was constructed.
+     */
+    isBond(): this is import('./BondSecurity').default;
     toString(): string;
     getFields(): FieldProto[];
     getField(field: FieldProto): any;
     getID(): UUID;
+    /**
+     * True iff this Security is a link reference (only the uuid is populated;
+     * other fields should not be relied on). See docs/adr/is_link_pattern.md.
+     * Pair with LinkResolver to hydrate to a full entity.
+     */
+    isLink(): boolean;
     getAsOf(): ZonedDateTime;
     getAssetClass(): string;
     getProductClass(): string;
     getProductType(): string;
     getSecurityID(): IdentifierProto;
-    getIssueDate(): LocalDate;
+    /**
+     * Returns the issue date if set, else null. Per-type semantic:
+     *   - Bond / TIPS / FRN: auction date.
+     *   - Equity: IPO listing date (when present in source data).
+     *   - CPI series: first observation date.
+     *   - Cash / FX: typically null.
+     *
+     * Returns null on equities/cash/etc. that don't have an issue date set,
+     * rather than throwing — issue date is optional on the base Security.
+     * For bond-specific code paths, prefer narrowing first via isBond() and
+     * calling BondSecurity.getIssueDate() (which returns LocalDate, not null).
+     */
+    getIssueDate(): LocalDate | null;
+    /**
+     * @deprecated Maturity date is a bond-only concept. On the base Security
+     * this still throws when unset for backwards compatibility. Prefer
+     * narrowing first:
+     *
+     *   if (sec.isBond()) sec.getMaturityDate();   // BondSecurity, returns LocalDate
+     *
+     * In a future major version this method will move to BondSecurity only
+     * and TS will catch the misuse at compile time.
+     */
     getMaturityDate(): LocalDate;
     /**
      * Returns the bond-like details sub-message from the oneof, if set.

package/node/wrappers/models/security/security.js

@@ -24,6 +24,24 @@ class Security {
                 return new Security(proto);
         }
     }
+    /**
+     * Type guard: true iff this Security is a BondSecurity (BOND_SECURITY,
+     * TIPS, or FRN). Use to narrow before calling bond-specific getters:
+     *
+     *   if (sec.isBond()) {
+     *     // sec: BondSecurity here — TS knows about getCouponRate(), etc.
+     *     console.log(sec.getMaturityDate());
+     *   }
+     *
+     * Implemented as a runtime check on the proto's securityType so it
+     * works regardless of how the wrapper was constructed.
+     */
+    isBond() {
+        const t = this.proto.getSecurityType();
+        return t === security_type_pb_1.SecurityTypeProto.BOND_SECURITY
+            || t === security_type_pb_1.SecurityTypeProto.TIPS
+            || t === security_type_pb_1.SecurityTypeProto.FRN;
+    }
     toString() {
         return `ID[${this.getID().toString()}], ${this.getSecurityID()}[${this.getIssuerName()}]`;
     }
@@ -49,8 +67,11 @@ class Security {
             case field_pb_1.FieldProto.ADJUSTED_TENOR:
                 throw new Error('Not implemented yet');
             case field_pb_1.FieldProto.MATURITY_DATE:
-                return this.getMaturityDate();
+                // Maturity date is bond-only. Mirror Java's Security.getField:
+                // delegate to BondSecurity, return null for non-bonds.
+                return this.isBond() ? this.getMaturityDate() : null;
             case field_pb_1.FieldProto.ISSUE_DATE:
+                // getIssueDate already returns null on non-bonds; just forward.
                 return this.getIssueDate();
             default:
                 throw new Error(`Field not mapped in Security wrapper: ${field}`);
@@ -62,6 +83,14 @@ class Security {
             throw new Error("UUID is required");
         return uuid_1.UUID.fromU8Array(uuid.getRawUuid_asU8());
     }
+    /**
+     * True iff this Security is a link reference (only the uuid is populated;
+     * other fields should not be relied on). See docs/adr/is_link_pattern.md.
+     * Pair with LinkResolver to hydrate to a full entity.
+     */
+    isLink() {
+        return this.proto.getIsLink();
+    }
     getAsOf() {
         const asOf = this.proto.getAsOf();
         if (!asOf)
@@ -85,14 +114,36 @@ class Security {
             throw new Error("Identifier is required");
         return identifier;
     }
+    /**
+     * Returns the issue date if set, else null. Per-type semantic:
+     *   - Bond / TIPS / FRN: auction date.
+     *   - Equity: IPO listing date (when present in source data).
+     *   - CPI series: first observation date.
+     *   - Cash / FX: typically null.
+     *
+     * Returns null on equities/cash/etc. that don't have an issue date set,
+     * rather than throwing — issue date is optional on the base Security.
+     * For bond-specific code paths, prefer narrowing first via isBond() and
+     * calling BondSecurity.getIssueDate() (which returns LocalDate, not null).
+     */
     getIssueDate() {
         // Prefer oneof bond sub-message if available, fall back to flat fields
         const bond = this.getBondLikeDetails();
         const date = bond ? bond.getIssueDate() : this.proto.getIssueDate();
         if (!date)
-            throw new Error("Issue date is required");
+            return null;
         return new date_1.LocalDate(date);
     }
+    /**
+     * @deprecated Maturity date is a bond-only concept. On the base Security
+     * this still throws when unset for backwards compatibility. Prefer
+     * narrowing first:
+     *
+     *   if (sec.isBond()) sec.getMaturityDate();   // BondSecurity, returns LocalDate
+     *
+     * In a future major version this method will move to BondSecurity only
+     * and TS will catch the misuse at compile time.
+     */
     getMaturityDate() {
         // Prefer oneof bond sub-message if available, fall back to flat fields
         const bond = this.getBondLikeDetails();

package/node/wrappers/models/security/security.js.map

@@ -1 +1 @@
-{"version":3,"file":"security.js","sourceRoot":"","sources":["security.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"security.js","sourceRoot":"","sources":["security.ts"],"names":[],"mappings":"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"}

package/node/wrappers/models/security/security.test.js

@@ -7,8 +7,10 @@ const local_date_pb_1 = require("../../../fintekkers/models/util/local_date_pb")
 const uuid_1 = require("../utils/uuid");
 const assert = require("assert");
 const security_1 = __importDefault(require("./security"));
+const BondSecurity_1 = __importDefault(require("./BondSecurity"));
 const decimal_value_pb_1 = require("../../../fintekkers/models/util/decimal_value_pb");
 const security_pb_1 = require("../../../fintekkers/models/security/security_pb");
+const security_type_pb_1 = require("../../../fintekkers/models/security/security_type_pb");
 const coupon_frequency_pb_1 = require("../../../fintekkers/models/security/coupon_frequency_pb");
 const coupon_type_pb_1 = require("../../../fintekkers/models/security/coupon_type_pb");
 const security_quantity_type_pb_1 = require("../../../fintekkers/models/security/security_quantity_type_pb");
@@ -19,6 +21,48 @@ function testSerialization() {
     const security = dummySecurity();
     assert(security.getMaturityDate().toDate().getFullYear() == 2026);
 }
+test('equity routes to base Security and isBond() returns false', () => {
+    const equity = dummyEquity();
+    expect(equity).toBeInstanceOf(security_1.default);
+    expect(equity).not.toBeInstanceOf(BondSecurity_1.default);
+    expect(equity.isBond()).toBe(false);
+});
+test('bond routes to BondSecurity and isBond() returns true (narrows type)', () => {
+    const bond = dummyBondSecurity();
+    expect(bond.isBond()).toBe(true);
+    if (bond.isBond()) {
+        // Inside the narrowed branch TS knows bond: BondSecurity.
+        // Calling a BondSecurity-only method here proves the narrowing works.
+        expect(bond.getCouponRate()).toBeDefined();
+    }
+});
+test('Security.getIssueDate returns null on equity (no throw)', () => {
+    const equity = dummyEquity();
+    // Phase 1 behavior change: was throw "Issue date is required", now returns null.
+    // This is the symptom fix that motivated #205 — equity wrappers no longer
+    // explode on per-record post-processing in ui-service.
+    expect(equity.getIssueDate()).toBeNull();
+});
+test('BondSecurity.getIssueDate returns LocalDate (non-nullable) on bond', () => {
+    const bond = dummyBondSecurity();
+    if (!bond.isBond())
+        throw new Error('test setup: expected bond');
+    const issueDate = bond.getIssueDate();
+    expect(issueDate).not.toBeNull();
+    expect(issueDate.toDate().getFullYear()).toBe(2021);
+});
+test('Security.getMaturityDate still throws on equity (Phase 1 deprecation, not removal)', () => {
+    const equity = dummyEquity();
+    // Behavior preserved deliberately for Phase 1 — callers still get a
+    // loud error if they don't narrow first. Removal happens in Phase 2.
+    expect(() => equity.getMaturityDate()).toThrow('Maturity date is required');
+});
+test('BondSecurity.getMaturityDate works on bond (inherited from Security)', () => {
+    const bond = dummyBondSecurity();
+    if (!bond.isBond())
+        throw new Error('test setup: expected bond');
+    expect(bond.getMaturityDate().toDate().getFullYear()).toBe(2026);
+});
 function dummySecurity() {
     return security_1.default.create(new security_pb_1.SecurityProto()
         .setObjectClass('Transaction').setVersion('0.0.1').setUuid(uuid_1.UUID.random().toUUIDProto())
@@ -33,4 +77,32 @@ function dummySecurity() {
         .setIssueDate(new local_date_pb_1.LocalDateProto().setYear(2021).setMonth(1).setDay(1))
         .setDescription("Dummy security"));
 }
+function dummyBondSecurity() {
+    // Same dummy security but with securityType set so the factory routes
+    // to BondSecurity.
+    return security_1.default.create(new security_pb_1.SecurityProto()
+        .setObjectClass('Security').setVersion('0.0.1').setUuid(uuid_1.UUID.random().toUUIDProto())
+        .setSecurityType(security_type_pb_1.SecurityTypeProto.BOND_SECURITY)
+        .setFaceValue(new decimal_value_pb_1.DecimalValueProto().setArbitraryPrecisionValue('1000.00'))
+        .setQuantityType(security_quantity_type_pb_1.SecurityQuantityTypeProto.ORIGINAL_FACE_VALUE)
+        .setAssetClass("Bond")
+        .setIssuerName("Dummy issuer")
+        .setCouponRate(new decimal_value_pb_1.DecimalValueProto().setArbitraryPrecisionValue('0.05'))
+        .setCouponFrequency(coupon_frequency_pb_1.CouponFrequencyProto.SEMIANNUALLY)
+        .setCouponType(coupon_type_pb_1.CouponTypeProto.FIXED)
+        .setMaturityDate(new local_date_pb_1.LocalDateProto().setYear(2026).setMonth(1).setDay(1))
+        .setIssueDate(new local_date_pb_1.LocalDateProto().setYear(2021).setMonth(1).setDay(1))
+        .setDescription("Dummy bond"));
+}
+function dummyEquity() {
+    // Equity has no maturity / issue date in the proto, exercising the
+    // null-return behavior on getIssueDate and the throw-on-missing
+    // behavior on getMaturityDate.
+    return security_1.default.create(new security_pb_1.SecurityProto()
+        .setObjectClass('Security').setVersion('0.0.1').setUuid(uuid_1.UUID.random().toUUIDProto())
+        .setSecurityType(security_type_pb_1.SecurityTypeProto.EQUITY_SECURITY)
+        .setAssetClass("Equity")
+        .setIssuerName("Dummy issuer Inc.")
+        .setDescription("Dummy equity"));
+}
 //# sourceMappingURL=security.test.js.map

package/node/wrappers/models/security/security.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"security.test.js","sourceRoot":"","sources":["security.test.ts"],"names":[],"mappings":";;;;;AAAA,iFAA+E;AAC/E,wCAAqC;AAErC,iCAAkC;AAClC,0DAAkC;AAElC,uFAAqF;AACrF,iFAAgF;AAChF,iGAA+F;AAC/F,uFAAqF;AACrF,6GAA0G;AAG1G,IAAI,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACnC,iBAAiB,EAAE,CAAC;AACxB,CAAC,CAAC,CAAC;AAEH,SAAS,iBAAiB;IACtB,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAC;IAEjC,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,aAAa;IAClB,OAAO,kBAAQ,CAAC,MAAM,CAAC,IAAI,2BAAa,EAAE;SACrC,cAAc,CAAC,aAAa,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,WAAI,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC;SACtF,YAAY,CAAC,IAAI,oCAAiB,EAAE,CAAC,0BAA0B,CAAC,SAAS,CAAC,CAAC;SAC3E,eAAe,CAAC,qDAAyB,CAAC,mBAAmB,CAAC;SAC9D,aAAa,CAAC,MAAM,CAAC;SACrB,aAAa,CAAC,cAAc,CAAC;SAE7B,aAAa,CAAC,IAAI,oCAAiB,EAAE,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC;SACzE,kBAAkB,CAAC,0CAAoB,CAAC,YAAY,CAAC;SACrD,aAAa,CAAC,gCAAe,CAAC,KAAK,CAAC;SAEpC,eAAe,CAAC,IAAI,8BAAc,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;SACzE,YAAY,CAAC,IAAI,8BAAc,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;SACtE,cAAc,CAAC,gBAAgB,CAAC,CACpC,CAAC;AACN,CAAC"}
+{"version":3,"file":"security.test.js","sourceRoot":"","sources":["security.test.ts"],"names":[],"mappings":"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"}

package/node/wrappers/models/security/security.test.ts

@@ -3,9 +3,11 @@ import { UUID } from '../utils/uuid';
 
 import assert = require('assert');
 import Security from './security';
+import BondSecurity from './BondSecurity';
 
 import { DecimalValueProto } from '../../../fintekkers/models/util/decimal_value_pb';
 import { SecurityProto } from '../../../fintekkers/models/security/security_pb';
+import { SecurityTypeProto } from '../../../fintekkers/models/security/security_type_pb';
 import { CouponFrequencyProto } from '../../../fintekkers/models/security/coupon_frequency_pb';
 import { CouponTypeProto } from '../../../fintekkers/models/security/coupon_type_pb';
 import { SecurityQuantityTypeProto } from '../../../fintekkers/models/security/security_quantity_type_pb';
@@ -21,6 +23,52 @@ function testSerialization(): void {
     assert(security.getMaturityDate().toDate().getFullYear() == 2026);
 }
 
+test('equity routes to base Security and isBond() returns false', () => {
+    const equity = dummyEquity();
+    expect(equity).toBeInstanceOf(Security);
+    expect(equity).not.toBeInstanceOf(BondSecurity);
+    expect(equity.isBond()).toBe(false);
+});
+
+test('bond routes to BondSecurity and isBond() returns true (narrows type)', () => {
+    const bond = dummyBondSecurity();
+    expect(bond.isBond()).toBe(true);
+    if (bond.isBond()) {
+        // Inside the narrowed branch TS knows bond: BondSecurity.
+        // Calling a BondSecurity-only method here proves the narrowing works.
+        expect(bond.getCouponRate()).toBeDefined();
+    }
+});
+
+test('Security.getIssueDate returns null on equity (no throw)', () => {
+    const equity = dummyEquity();
+    // Phase 1 behavior change: was throw "Issue date is required", now returns null.
+    // This is the symptom fix that motivated #205 — equity wrappers no longer
+    // explode on per-record post-processing in ui-service.
+    expect(equity.getIssueDate()).toBeNull();
+});
+
+test('BondSecurity.getIssueDate returns LocalDate (non-nullable) on bond', () => {
+    const bond = dummyBondSecurity();
+    if (!bond.isBond()) throw new Error('test setup: expected bond');
+    const issueDate = bond.getIssueDate();
+    expect(issueDate).not.toBeNull();
+    expect(issueDate.toDate().getFullYear()).toBe(2021);
+});
+
+test('Security.getMaturityDate still throws on equity (Phase 1 deprecation, not removal)', () => {
+    const equity = dummyEquity();
+    // Behavior preserved deliberately for Phase 1 — callers still get a
+    // loud error if they don't narrow first. Removal happens in Phase 2.
+    expect(() => equity.getMaturityDate()).toThrow('Maturity date is required');
+});
+
+test('BondSecurity.getMaturityDate works on bond (inherited from Security)', () => {
+    const bond = dummyBondSecurity();
+    if (!bond.isBond()) throw new Error('test setup: expected bond');
+    expect(bond.getMaturityDate().toDate().getFullYear()).toBe(2026);
+});
+
 function dummySecurity() {
     return Security.create(new SecurityProto()
         .setObjectClass('Transaction').setVersion('0.0.1').setUuid(UUID.random().toUUIDProto())
@@ -39,3 +87,35 @@ function dummySecurity() {
     );
 }
 
+function dummyBondSecurity() {
+    // Same dummy security but with securityType set so the factory routes
+    // to BondSecurity.
+    return Security.create(new SecurityProto()
+        .setObjectClass('Security').setVersion('0.0.1').setUuid(UUID.random().toUUIDProto())
+        .setSecurityType(SecurityTypeProto.BOND_SECURITY)
+        .setFaceValue(new DecimalValueProto().setArbitraryPrecisionValue('1000.00'))
+        .setQuantityType(SecurityQuantityTypeProto.ORIGINAL_FACE_VALUE)
+        .setAssetClass("Bond")
+        .setIssuerName("Dummy issuer")
+        .setCouponRate(new DecimalValueProto().setArbitraryPrecisionValue('0.05'))
+        .setCouponFrequency(CouponFrequencyProto.SEMIANNUALLY)
+        .setCouponType(CouponTypeProto.FIXED)
+        .setMaturityDate(new LocalDateProto().setYear(2026).setMonth(1).setDay(1))
+        .setIssueDate(new LocalDateProto().setYear(2021).setMonth(1).setDay(1))
+        .setDescription("Dummy bond")
+    );
+}
+
+function dummyEquity() {
+    // Equity has no maturity / issue date in the proto, exercising the
+    // null-return behavior on getIssueDate and the throw-on-missing
+    // behavior on getMaturityDate.
+    return Security.create(new SecurityProto()
+        .setObjectClass('Security').setVersion('0.0.1').setUuid(UUID.random().toUUIDProto())
+        .setSecurityType(SecurityTypeProto.EQUITY_SECURITY)
+        .setAssetClass("Equity")
+        .setIssuerName("Dummy issuer Inc.")
+        .setDescription("Dummy equity")
+    );
+}
+

package/node/wrappers/models/security/security.ts

@@ -29,6 +29,25 @@ class Security {
     }
   }
 
+  /**
+   * Type guard: true iff this Security is a BondSecurity (BOND_SECURITY,
+   * TIPS, or FRN). Use to narrow before calling bond-specific getters:
+   *
+   *   if (sec.isBond()) {
+   *     // sec: BondSecurity here — TS knows about getCouponRate(), etc.
+   *     console.log(sec.getMaturityDate());
+   *   }
+   *
+   * Implemented as a runtime check on the proto's securityType so it
+   * works regardless of how the wrapper was constructed.
+   */
+  isBond(): this is import('./BondSecurity').default {
+    const t = this.proto.getSecurityType();
+    return t === SecurityTypeProto.BOND_SECURITY
+        || t === SecurityTypeProto.TIPS
+        || t === SecurityTypeProto.FRN;
+  }
+
 
   toString(): string {
     return `ID[${this.getID().toString()}], ${this.getSecurityID()}[${this.getIssuerName()}]`;
@@ -57,8 +76,11 @@ class Security {
       case FieldProto.ADJUSTED_TENOR:
         throw new Error('Not implemented yet');
       case FieldProto.MATURITY_DATE:
-        return this.getMaturityDate();
+        // Maturity date is bond-only. Mirror Java's Security.getField:
+        // delegate to BondSecurity, return null for non-bonds.
+        return this.isBond() ? this.getMaturityDate() : null;
       case FieldProto.ISSUE_DATE:
+        // getIssueDate already returns null on non-bonds; just forward.
         return this.getIssueDate();
       default:
         throw new Error(`Field not mapped in Security wrapper: ${field}`);
@@ -71,6 +93,15 @@ class Security {
     return UUID.fromU8Array(uuid.getRawUuid_asU8());
   }
 
+  /**
+   * True iff this Security is a link reference (only the uuid is populated;
+   * other fields should not be relied on). See docs/adr/is_link_pattern.md.
+   * Pair with LinkResolver to hydrate to a full entity.
+   */
+  isLink(): boolean {
+    return this.proto.getIsLink();
+  }
+
   getAsOf(): ZonedDateTime {
     const asOf = this.proto.getAsOf();
     if (!asOf) throw new Error("AsOf is required");
@@ -100,14 +131,36 @@ class Security {
     return identifier;
   }
 
-  getIssueDate(): LocalDate {
+  /**
+   * Returns the issue date if set, else null. Per-type semantic:
+   *   - Bond / TIPS / FRN: auction date.
+   *   - Equity: IPO listing date (when present in source data).
+   *   - CPI series: first observation date.
+   *   - Cash / FX: typically null.
+   *
+   * Returns null on equities/cash/etc. that don't have an issue date set,
+   * rather than throwing — issue date is optional on the base Security.
+   * For bond-specific code paths, prefer narrowing first via isBond() and
+   * calling BondSecurity.getIssueDate() (which returns LocalDate, not null).
+   */
+  getIssueDate(): LocalDate | null {
     // Prefer oneof bond sub-message if available, fall back to flat fields
     const bond = this.getBondLikeDetails();
     const date = bond ? bond.getIssueDate() : this.proto.getIssueDate();
-    if (!date) throw new Error("Issue date is required");
+    if (!date) return null;
     return new LocalDate(date);
   }
 
+  /**
+   * @deprecated Maturity date is a bond-only concept. On the base Security
+   * this still throws when unset for backwards compatibility. Prefer
+   * narrowing first:
+   *
+   *   if (sec.isBond()) sec.getMaturityDate();   // BondSecurity, returns LocalDate
+   *
+   * In a future major version this method will move to BondSecurity only
+   * and TS will catch the misuse at compile time.
+   */
   getMaturityDate(): LocalDate {
     // Prefer oneof bond sub-message if available, fall back to flat fields
     const bond = this.getBondLikeDetails();

package/node/wrappers/services/price-service/PriceService.d.ts

@@ -4,6 +4,7 @@ import { LocalTimestampProto } from '../../../fintekkers/models/util/local_times
 import { PriceProto } from '../../../fintekkers/models/price/price_pb';
 import { SummaryProto } from '../../../fintekkers/requests/util/errors/summary_pb';
 import { CreatePriceResponseProto } from '../../../fintekkers/requests/price/create_price_response_pb';
+import LinkResolver from '../../util/link-resolver';
 declare class PriceService {
     private client;
     constructor(apiKey?: string);
@@ -25,5 +26,23 @@ declare class PriceService {
      *   priceService.searchBySecurityId('18e8c4e6-3da0-47c9-...')
      */
     searchBySecurityId(securityId: string, asOf?: LocalTimestampProto): Promise<Price[]>;
+    /**
+     * Search prices and hydrate each Price's embedded Security from link
+     * to full entity in a single batched lookup. Equivalent to:
+     *
+     *   const prices = await priceService.search(asOf, filter);
+     *   await new LinkResolver().resolveSecurities(prices);
+     *
+     * but with the LinkResolver instance reusable across calls (cache hits
+     * benefit subsequent lookups).
+     *
+     * Pass a shared `linkResolver` to share caching across multiple
+     * service-wrapper calls in the same request scope. If omitted, a new
+     * resolver is constructed per call (no cross-call cache reuse).
+     *
+     * Mutates each returned Price.proto's embedded SecurityProto in place
+     * (link → full). See LinkResolver for cache + dedupe semantics.
+     */
+    searchWithSecurities(asOf: LocalTimestampProto, positionFilter: PositionFilter, linkResolver?: LinkResolver): Promise<Price[]>;
 }
 export { PriceService };