feat(sdk): add EntityIdentifier convenience constructors

[marythought]

Summary

• Add forEmail, forClientId, forUserName, forToken, and withRequestToken helper functions that mirror the Go SDK's EntityIdentifier constructors
• Reduces authorization call setup from ~15 lines of nested object literals to a single function call
• Exported from @opentdf/sdk top-level

Before:

const response = await platform.v2.authorization.getDecision({
  entityIdentifier: {
    identifier: {
      case: 'entityChain',
      value: {
        entities: [
          {
            entityType: {
              case: 'emailAddress',
              value: 'jen@example.com',
            },
            category: Entity_Category.SUBJECT,
          },
        ],
      },
    },
  },
  action: { name: 'read' },
  resource: {
    resource: {
      case: 'attributeValues',
      value: {
        fqns: ['https://example.com/attr/department/value/finance'],
      },
    },
  },
});

After:

import { forEmail } from '@opentdf/sdk';

const response = await platform.v2.authorization.getDecision({
  entityIdentifier: forEmail('jen@example.com'),
  action: { name: 'read' },
  resource: {
    resource: {
      case: 'attributeValues',
      value: {
        fqns: ['https://example.com/attr/department/value/finance'],
      },
    },
  },
});

Test plan

• 9 mocha tests covering all 5 helpers with valid and empty string inputs
• Prettier + ESLint clean

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added helper functions for constructing authorization entity identifiers. Enables identifying entities by email address, client ID, username, JWT token, or automatic extraction of tokens from request authorization headers for simplified implementation and seamless integration.

• Tests

  • Added comprehensive unit tests for entity identifier helper functions, including validation of all identifier types and edge cases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a0eb933e-b44c-455a-a636-29ec6c7e09b1

📥 Commits

Reviewing files that changed from the base of the PR and between 07f57e7 and b6edb66.

📒 Files selected for processing (1)

• lib/tests/mocha/unit/entity-identifiers.spec.ts

✅ Files skipped from review due to trivial changes (1)

• lib/tests/mocha/unit/entity-identifiers.spec.ts

---

📝 Walkthrough

Walkthrough

A new authorization entity-identifier helper module adds five convenience constructors (forEmail, forClientId, forUserName, forToken, withRequestToken) that produce pre-built EntityIdentifier protobuf objects and are re-exported from the package index; unit tests were added to validate their outputs.

Changes

Cohort / File(s)	Summary
Entity Identifier Helpers lib/src/index.ts, lib/src/platform/authorization/entity-identifiers.ts	Added a new module exporting five helper functions that construct EntityIdentifier protobuf messages for email, clientId, userName, token, and request-derived token; main index re-exports these helpers.
Unit Tests lib/tests/mocha/unit/entity-identifiers.spec.ts	New Mocha/Chai test suite asserting each helper returns the expected identifier.case, embedded protobuf fields, preserved input strings (including empty), and Entity_Category.SUBJECT where applicable.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hopped a helper, swift and neat,
Building identifiers one-by-one, sweet.
Email, client, name, and token true,
A request-token wink — derived for you.
Protobuf carrots, tidy and bright! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding five new EntityIdentifier convenience constructor functions to the SDK.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/DSPX-2794-entity-identifier-helpers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

lib/tests/mocha/unit/entity-identifiers.spec.ts (1)

2-8: Prefer importing helpers from the SDK entrypoint in at least one test.

Line 2–8 tests the internal module directly, so it won’t catch accidental regressions in the new top-level exports from lib/src/index.ts. Consider importing from ../../../src/index.js (or adding one small entrypoint-focused test).

💡 Minimal test import adjustment

 import { expect } from 'chai';
 import {
   forEmail,
   forClientId,
   forUserName,
   forToken,
   withRequestToken,
-} from '../../../src/platform/authorization/entity-identifiers.js';
+} from '../../../src/index.js';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/tests/mocha/unit/entity-identifiers.spec.ts` around lines 2 - 8, The test
currently imports helper functions (forEmail, forClientId, forUserName,
forToken, withRequestToken) directly from the internal module
entity-identifiers.js which won't catch changes to the package's top-level
exports; update at least one test (e.g., in entity-identifiers.spec.ts) to
import those same symbols from the SDK entrypoint (../../../src/index.js) or add
a small new test that imports from the entrypoint and asserts the helpers are
defined/behave as expected so regressions in lib/src/index.ts are detected.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@lib/tests/mocha/unit/entity-identifiers.spec.ts`:
- Around line 2-8: The test currently imports helper functions (forEmail,
forClientId, forUserName, forToken, withRequestToken) directly from the internal
module entity-identifiers.js which won't catch changes to the package's
top-level exports; update at least one test (e.g., in
entity-identifiers.spec.ts) to import those same symbols from the SDK entrypoint
(../../../src/index.js) or add a small new test that imports from the entrypoint
and asserts the helpers are defined/behave as expected so regressions in
lib/src/index.ts are detected.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ce296dd3-66e3-4a9b-a137-1f8a08a64246

📥 Commits

Reviewing files that changed from the base of the PR and between c412bc9 and 07f57e7.

📒 Files selected for processing (3)

• lib/src/index.ts
• lib/src/platform/authorization/entity-identifiers.ts
• lib/tests/mocha/unit/entity-identifiers.spec.ts

[gemini-code-assist]

Code Review

This pull request introduces a set of convenience constructors for EntityIdentifier to mirror the Go SDK's functionality, including helpers for email, client ID, username, and tokens. It also adds corresponding unit tests. The review feedback suggests improving parity with the Go SDK by adding a helper for registeredResourceValueFqn and exporting the forEntity function to allow for custom entity identifiers.

[github-actions]

X-Test Results

✅ js-main
✅ js-v0.9.0
✅ java-main
✅ java-v0.9.0
✅ go-main
✅ go-v0.9.0
opentdf-ctl
opentdf-sdk-lib

[github-actions]

X-Test Results

✅ js-main
✅ js-v0.9.0
✅ java-main
✅ go-main
✅ java-v0.9.0
✅ go-v0.9.0
opentdf-ctl
opentdf-sdk-lib

[eugenioenko]

🎉