From 3f83aeca6ae809b7ee5975454bb26f88a7da0980 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 10 Apr 2026 14:09:39 -0700 Subject: [PATCH 1/3] refactor(sdk): namespace EntityIdentifier helpers under EntityIdentifiers Export helpers as `EntityIdentifiers.forEmail(...)` instead of bare `forEmail(...)` to avoid top-level name collisions (e.g. with future TDF recipient helpers) and align with the Java SDK pattern. Closes #915 Co-Authored-By: Claude Opus 4.6 (1M context) --- lib/src/index.ts | 8 +------- .../mocha/unit/entity-identifiers.spec.ts | 18 ++++++------------ 2 files changed, 7 insertions(+), 19 deletions(-) diff --git a/lib/src/index.ts b/lib/src/index.ts index 86c2f6f13..36bb33f78 100644 --- a/lib/src/index.ts +++ b/lib/src/index.ts @@ -19,13 +19,7 @@ export { type ExternalJwtTokenProviderOptions, } from './auth/token-providers.js'; export { attributeFQNsAsValues } from './policy/api.js'; -export { - forEmail, - forClientId, - forUserName, - forToken, - withRequestToken, -} from './platform/authorization/entity-identifiers.js'; +export * as EntityIdentifiers from './platform/authorization/entity-identifiers.js'; export { listAttributes, validateAttributes, diff --git a/lib/tests/mocha/unit/entity-identifiers.spec.ts b/lib/tests/mocha/unit/entity-identifiers.spec.ts index 0c85fcb54..c4203d9e7 100644 --- a/lib/tests/mocha/unit/entity-identifiers.spec.ts +++ b/lib/tests/mocha/unit/entity-identifiers.spec.ts @@ -1,11 +1,5 @@ import { expect } from 'chai'; -import { - forEmail, - forClientId, - forUserName, - forToken, - withRequestToken, -} from '../../../src/index.js'; +import { EntityIdentifiers } from '../../../src/index.js'; import { Entity_Category } from '../../../src/platform/entity/entity_pb.js'; import type { EntityChain, Token } from '../../../src/platform/entity/entity_pb.js'; import type { BoolValue } from '@bufbuild/protobuf/wkt'; @@ -14,7 +8,7 @@ describe('EntityIdentifier helpers', () => { describe('forEmail()', () => { for (const email of ['user@example.com', '']) { it(`builds an entityChain with emailAddress="${email}"`, () => { - const eid = forEmail(email); + const eid = EntityIdentifiers.forEmail(email); expect(eid.identifier.case).to.equal('entityChain'); const chain = eid.identifier.value as EntityChain; expect(chain.entities).to.have.lengthOf(1); @@ -29,7 +23,7 @@ describe('EntityIdentifier helpers', () => { describe('forClientId()', () => { for (const clientId of ['my-client', '']) { it(`builds an entityChain with clientId="${clientId}"`, () => { - const eid = forClientId(clientId); + const eid = EntityIdentifiers.forClientId(clientId); expect(eid.identifier.case).to.equal('entityChain'); const chain = eid.identifier.value as EntityChain; expect(chain.entities).to.have.lengthOf(1); @@ -44,7 +38,7 @@ describe('EntityIdentifier helpers', () => { describe('forUserName()', () => { for (const userName of ['alice', '']) { it(`builds an entityChain with userName="${userName}"`, () => { - const eid = forUserName(userName); + const eid = EntityIdentifiers.forUserName(userName); expect(eid.identifier.case).to.equal('entityChain'); const chain = eid.identifier.value as EntityChain; expect(chain.entities).to.have.lengthOf(1); @@ -59,7 +53,7 @@ describe('EntityIdentifier helpers', () => { describe('forToken()', () => { for (const jwt of ['eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.test', '']) { it(`builds a token identifier with jwt="${jwt.slice(0, 20)}..."`, () => { - const eid = forToken(jwt); + const eid = EntityIdentifiers.forToken(jwt); expect(eid.identifier.case).to.equal('token'); expect((eid.identifier.value as Token).jwt).to.equal(jwt); }); @@ -68,7 +62,7 @@ describe('EntityIdentifier helpers', () => { describe('withRequestToken()', () => { it('builds a withRequestToken identifier set to true', () => { - const eid = withRequestToken(); + const eid = EntityIdentifiers.withRequestToken(); expect(eid.identifier.case).to.equal('withRequestToken'); expect((eid.identifier.value as BoolValue).value).to.equal(true); }); From d0a54aa96a3f7716fd98bb4bf065078554f726d2 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 10 Apr 2026 14:16:13 -0700 Subject: [PATCH 2/3] chore(sdk): update JSDoc example to use namespaced import Co-Authored-By: Claude Opus 4.6 (1M context) --- lib/src/platform/authorization/entity-identifiers.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/src/platform/authorization/entity-identifiers.ts b/lib/src/platform/authorization/entity-identifiers.ts index 6329db0d9..e62ebda3e 100644 --- a/lib/src/platform/authorization/entity-identifiers.ts +++ b/lib/src/platform/authorization/entity-identifiers.ts @@ -35,7 +35,8 @@ import { * }); * * // After - * const eid = forEmail('jen@example.com'); + * import { EntityIdentifiers } from '@opentdf/sdk'; + * const eid = EntityIdentifiers.forEmail('jen@example.com'); * ``` */ From c525eee5c50f0499e1c70785b4e37b0a2bd3be88 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 10 Apr 2026 14:34:44 -0700 Subject: [PATCH 3/3] chore(sdk): deprecate bare EntityIdentifier exports, keep for compat Keep the bare named exports (forEmail, forClientId, etc.) with @deprecated JSDoc tags so existing consumers don't break. The namespaced EntityIdentifiers export is the recommended path forward. Co-Authored-By: Claude Opus 4.6 (1M context) --- lib/src/index.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/lib/src/index.ts b/lib/src/index.ts index 36bb33f78..553c08a4d 100644 --- a/lib/src/index.ts +++ b/lib/src/index.ts @@ -20,6 +20,16 @@ export { } from './auth/token-providers.js'; export { attributeFQNsAsValues } from './policy/api.js'; export * as EntityIdentifiers from './platform/authorization/entity-identifiers.js'; +/** @deprecated Use `EntityIdentifiers.forEmail()` instead. Will be removed in a future release. */ +export { forEmail } from './platform/authorization/entity-identifiers.js'; +/** @deprecated Use `EntityIdentifiers.forClientId()` instead. Will be removed in a future release. */ +export { forClientId } from './platform/authorization/entity-identifiers.js'; +/** @deprecated Use `EntityIdentifiers.forUserName()` instead. Will be removed in a future release. */ +export { forUserName } from './platform/authorization/entity-identifiers.js'; +/** @deprecated Use `EntityIdentifiers.forToken()` instead. Will be removed in a future release. */ +export { forToken } from './platform/authorization/entity-identifiers.js'; +/** @deprecated Use `EntityIdentifiers.withRequestToken()` instead. Will be removed in a future release. */ +export { withRequestToken } from './platform/authorization/entity-identifiers.js'; export { listAttributes, validateAttributes,