Add readObjectByName method for Vault API (#1424)

## Description

This new endpoint matches the response of the existing ID-based read
method. Names have enforced uniqueness.

## Documentation

Does this require changes to the WorkOS Docs? E.g. the [API
Reference](https://workos.com/docs/reference) or code snippets need
updates.

```
[x] Yes
```

If yes, link a related docs PR and add a docs maintainer as a reviewer.
Their approval is required.

workos/workos#49220

Author: hexedpackets

src/vault/vault-live-test.spec.ts

@@ -70,6 +70,38 @@ describe.skip('Vault Live Test', () => {
       });
     });
 
+    it('Reads objects by name', async () => {
+      const objectName = `${objectPrefix}-nazca`;
+      const newObject = await workos.vault.createObject({
+        name: objectName,
+        value: 'Suri 10-15 micron',
+        context: { fiber: 'Alpalca' },
+      });
+
+      const expectedMetadata = {
+        id: expect.any(String),
+        context: {
+          fiber: 'Alpalca',
+        },
+        environmentId: expect.any(String),
+        keyId: expect.any(String),
+        updatedAt: expect.any(Date),
+        updatedBy: {
+          id: expect.any(String),
+          name: expect.any(String),
+        },
+        versionId: expect.any(String),
+      };
+
+      const objectValue = await workos.vault.readObjectByName(objectName);
+      expect(objectValue).toStrictEqual({
+        id: newObject.id,
+        name: objectName,
+        value: 'Suri 10-15 micron',
+        metadata: expectedMetadata,
+      });
+    });
+
     it('Fails to create objects with the same name', async () => {
       const objectName = `${objectPrefix}-lima`;
       await workos.vault.createObject({
@@ -173,7 +205,7 @@ describe.skip('Vault Live Test', () => {
       const newObject = await workos.vault.createObject({
         name: objectName,
         value: 'Qiviut 11-13 micron',
-        context: { fiber: 'Musk Ox' },
+        context: { fiber: 'MuskOx' },
       });
 
       const objectDescription = await workos.vault.describeObject({
@@ -183,7 +215,7 @@ describe.skip('Vault Live Test', () => {
       const expectedMetadata = {
         id: expect.any(String),
         context: {
-          fiber: 'Musk Ox',
+          fiber: 'MuskOx',
         },
         environmentId: expect.any(String),
         keyId: expect.any(String),
@@ -213,7 +245,7 @@ describe.skip('Vault Live Test', () => {
         await workos.vault.createObject({
           name: objectName,
           value: 'Qiviut 11-13 micron',
-          context: { fiber: 'Musk Ox' },
+          context: { fiber: 'MuskOx' },
         });
         objectNames.push(objectName);
       }
@@ -296,7 +328,7 @@ describe.skip('Vault Live Test', () => {
       const aad = 'seq1';
       const encrypted = await workos.vault.encrypt(data, keyContext, aad);
       await expect(() => workos.vault.decrypt(encrypted)).rejects.toThrow(
-        'unable to authenticate data',
+        'The operation failed for an operation-specific reason',
       );
     });
   });

src/vault/vault.spec.ts

@@ -125,6 +125,32 @@ describe('Vault', () => {
     });
   });
 
+  describe('readObjectByName', () => {
+    it('reads an object by name', async () => {
+      const objectName = 'lima';
+      const objectId = 'secret1';
+      fetchOnce({
+        id: objectId,
+        metadata: {
+          id: objectId,
+          context: { emporer: 'groove' },
+          environment_id: 'environment_d',
+          key_id: 'key1',
+          updated_at: '2025-03-11T02:18:54.250931Z',
+          updated_by: { id: 'key_xxx', name: 'Local Test Key' },
+          version_id: 'version1',
+        },
+        name: objectName,
+        value: 'Pull the lever Gronk',
+      });
+      const resource = await workos.vault.readObjectByName(objectName);
+      expect(fetchURL()).toContain(`/vault/v1/kv/name/${objectName}`);
+      expect(fetchMethod()).toBe('GET');
+      expect(resource.name).toBe(objectName);
+      expect(resource.id).toBe(objectId);
+    });
+  });
+
   describe('listSecrets', () => {
     it('gets a paginated list of secrets', async () => {
       fetchOnce({

src/vault/vault.ts

@@ -114,6 +114,13 @@ export class Vault {
     return deserializeObject(data);
   }
 
+  async readObjectByName(name: string): Promise<VaultObject> {
+    const { data } = await this.workos.get<ReadObjectResponse>(
+      `/vault/v1/kv/name/${encodeURIComponent(name)}`,
+    );
+    return deserializeObject(data);
+  }
+
   async describeObject(options: ReadObjectOptions): Promise<VaultObject> {
     const { data } = await this.workos.get<ReadObjectResponse>(
       `/vault/v1/kv/${encodeURIComponent(options.id)}/metadata`,